The recent surge in the popularity of APIs among the consumer public has sent companies scrambling to the programmer’s drawing board to devise their own. Much of this has to do with the continuing trends of portability in electronic devices (e.g, Smartphones and Tablets) which – as it turns out – are a natural medium for the apps that function as the preferred interface for API-customer interaction.
The very first consideration before building an API comes – not surprisingly – from a bit of research. A company should employ comprehensive analytical tools to discern where their visitors are coming from, what they like the most, and any other relevant details of their interaction with the application for which said company will eventually build an interface for cross-program compatibility. These are the foundational details that can eventually make-or-break an API. They should be done before any programming begins.
The language of choice will likely be determined by the size of the company for which the API is being built. For the enterprise-level corporation, the more complex (and arguably more capable) SOAP protocol could be easier to use in the beginning. Certainly a lot of service-oriented applications are already using it and exposing themselves through SOAP. AT the same time, the alternative REST model has the advantage of working more naturally with http and URL calls. This is useful for consumers who, after all, access Web-pages regularly. As an addendum to the language choice, returning data when requested will need to be handled by either an XML or a JSON data-exchange format. Most app-developers agree that JSON suits the customer-centric mantra espoused by most APIs: being easier to read and manipulate by humans as opposed to search engine spiders and other computerized elements.
In the past, SOAP was popular. Today, RESTful applications tend to have more advantages and be more compatible (along with the JSON data-interchange format) with most of the other applications out there. This is especially true for mobile apps. With mobile marketing surging forward, it’s easy to see why this consideration would be so important to building the best API. There is significant complexity involved in shifting an API built on the shell of a SOAP server interface over to the more popular RESTful platform of today, but API management solutions can help. They are often found in developer community software.
After the groundwork has been laid, and the API put together, it has to be promoted. Otherwise, it will languish unseen in a graveyard full of other apps that aren’t being marketed. Publishing it is a necessity that facilitates sharing with other programmers, businesses and customers. Promotion should take place in a forum that has many supportive tools that span the gamut from capable security measures, a suite of tools that aid documentation and content management for longevity, and a system that makes it easy to search and find using accurate keywords and app-API connections. These things should be ascertained before socialization, in fact, because security will be a concern if the API happens to go viral and become available to any number of unknowns.
In an interview with SD Times, John Musser, Programmable Web founder listed the top 10 API development worst practices as:
10. Poor error handling
9. REST APIs that ignore HTTP rules
8. Exposing your raw underlying data model
7. Security complexity
6. Unexpected and undocumented releases
5. Poor developer experience
4. Expecting an MVC framework automatically means you have a great API
3. Assuming that if you build it, they will come
2. Inadequate support
1. Poor documentation
As a final measure before joining social forums and readying an API to be keyword-searchable in catalogs, decisions should be made regarding accessibility. Will it be open to everybody, as is the case with eBay? Or mostly everybody, like the Twitter API? Will it be relatively closed, such as the Google Maps API, with permissions granted only by user request and subsequent authentication? There are benefits and undesirable possibilities with each approach. Ideally, the traffic and economic potential should be balanced out by the potential for abuse and misuse. After the decision is made, a developer community can function as the launch-pad from which the API takes off with confidence.