API stands for Application Programming Interface.  I'm sure you wouldn't be reading my post if you aren't aware what it is.

From Wikipedia:

An application programming interface (API) is a source code-based specification intended to be used as an interface by software components to communicate with each other. An API may include specifications for routines, data structures, object classes, and variables.

-- http://en.wikipedia.org/wiki/Application_programming_interface


I wouldn't delve so much into what it is and what it isn't, but I'll got straight to describing what its pros and cons are in different business scenarios.  With this post, I have listed some of my own tips to share that could help you out in making good decisions for your product platform and implementation.

How do you know if your product needs an API?

First, check and verify if you really need this.  You don't want to waste an entire architecture and even your development and testing resource if you go straight to making this available without the right purpose/audience.

  1. Your product has several core objects.

Facebook has one core object and several associations.  The core object is the profile, which is connected to several posts, friends, links, notes.

Several "isolated" (but possibly tangent) core objects, like a profile, job postings, job applications, articles, etc.  Then your product will surely need an API.

2.  Your product's business roadmap includes external partnerships.

If you plan to put your product to several external partnerships, thereby gaining leverage to the volume of your data; then you would most likely need an API.

3.  Your intend to make use of your product's data to create a new product

The volume of data you collect may be presented in a different manner.  A job application board application may end up collecting profiles.  These profiles can then be used possibly by a recruiter application.

4.  Integrity of data coming from external inputs

Since web applications have been evolving to more and more aesthetic improvements using javascript and other front-end libraries, gathering data from user inputs become easier and provides flexible inputs from forms.  This in turn provides complexity in terms of code and data processing.  Data needs to be cleaned, more often than not.

Gathering inputs from external sources thru the API is strictly black and white.  Data format checking is strict and provides you more power in quickly gathering clean, useful data.

5.  Providing margin for premium

If you intend to only disclose parts of your data via API, then this could be a value added service that you can offer.

How do you choose the right option for moving around your data to and fro external applications?

If you are planning to use external tools for moving around your data, and they offer several approaches, how do you decide which one would be best?  and to which scenarios would you prefer one over the other?

  1. They offer data tracking via scripts

These usually come in the form of javascript snippets that are trackers like the famous google analytics urchin code.

This option is best for voluminous requests and for tracking hits.  You aren't concerned with 100% accuracy, but only 80-90% of data is sufficient enough.  Why?  You usually use this only to verify that your speculation is correct, or to identify majority of your source of traffic and create specific targets.

2.  They offer iframe solutions

This is the least secure way of gathering your data.  Its a must to use this only for GET requests.  If you must need to pass sessions, payments, passwords, then this is not your option.

It is best to use this only to gather data that you wouldn't be afraid to lose.  This is best for gathering survey inputs, questionnaire responses and/or confirmation for event attendance, etc.

Any amount of data to or from this iframe should always be subject to serious security scrutinizing.

3.  They offer data tracking via API requests

Use this only as needed.

Benefits:

a.  This is the best option for sending secure data.

b.  This is best used when you are particular with the freshness of data.

c.  If you are only concerned with GET and POST of data and front end is a minor factor

Disadvantages:

a.  This is usually a premium service, depending on the product.

b.  A maximum threshold is usually offered to limit the cost of querying on their servers.

What factors to consider when creating an API
  1. Separate context of paid and free API

If at first, you have secured a firm decision that your product needs an API, allot a dedicated server only for your API traffic.  At first, it is possible that you can host both the free and the paid API host under one server.

Do be wary about both context's traffic.  Watch their traffic carefully because free API requests may eventually need to be housed in another server so as not to disrupt the quality and turnaround time for the premium API requests.

2.  Make the necessary measures to secure the premium API

a.  Registration.  Require distinct credentials per access.

b.  Vigilant Maintenance.  Require occasional flushes of tokens and scheduled maintenance to reinforce systems security.

c.  Define limits.  Premium API must also have ceiling of requests to protect the quality of response which includes speed, accuracy and freshness of data.

3.  Scope is defined

An API should always be well defined in scope.  Very lean and target oriented.  Make sure that you define actions that your API would serve.  If it gets too bloated, then it can't be classified as an API but probably already just another isolated application.

Some actions may seem to be harder to implement via API, wherein a web interface would be best.  Some of these can be: uploading of photos, replacing avatars, etc.

Sample of a clean, lean scope would be: upload job post, get a job post, delete a job post, expire a job post.

This is not  a finite list nor is it a strict list, but a collection of lessons, learnings and tips that might save the day of another IT manager.  :)

Feel free to add in to this list by sharing your own thoughts and experience.