The successes of social networking phenomena such as Facebook, Twitter, and other popular engines weren’t achieved by their in-house product being available on all platforms. Instead, they became overnight successes because the product was offered as easily consumable APIs that developers like us built apps on top of.
This phenomenon is referred to within tech circles as platforming an offering. In essence, this means that the product offering is architected and exposed in such a way that the consumers of the product call it as if it were a platform API. When this happens, the developer ecosystem for those APIs thrives because developers are not coupled to consume the entire product, only the features they are interested in.
Here are the considerations that go into determining how to build APIs for your product.
APIs can be exposed in a variety of protocols. Two of the most popular protocols are SOAP and REST.
SOAP was popular earlier on, but REST has now taken over as the de facto protocol for modern web services. Almost all popular APIs in the world out there today are REST APIs.
REST (Representational State Transfer) is a style for communicating over HTTP with the same verbs that HTTP uses (GET, POST, PUT, DELETE). REST was developed by the W3C Technical Architecture Group.
The next consideration that developers have to plan for is the format in which data will sent and received from the service. XML can be used with both SOAP and REST protocols, but if you are building a RESTful service, JSON is the obvious choice. There is support for JSON encoders and decoders in every major language, including Java, .NET, and Objective C.
Operations for Updating and Retrieving Data
If you are building RESTful services for your application, be sure to be consistent with REST and HTTP standards. This means that, in any operation where you get data/state of a component, you use a “GET” operation. When you want to create or UPATE something, you would use POST/PUT operation. If you are removing something, you would do that via the DELETE operation. Being consistent with REST and HTTP standards will avoid customer frustration when they notice system behavior to be different for an operation.
Authentication and Security
I highly recommend that you implement authentication in your APIs (unless you have a business reason to allow unauthenticated calls). If you need to implement authentication, use industry standard protocols such as oAuth2.0 or roll out your own token based or HTTP-based authentication.
Sticking with industry standards will be the simplest for your API callers to consume, so think about that when you design your APIs.
Besides using authentication, you should SSL your calls. The overhead is insignificant and the benefit is obvious.
As mentioned earlier, adhere to HTTP standards as much as possible. This means your API will return the same error codes as other REST APIs: Client errors are 4xx and server errors are 5xx. Successes are reported via 2xx codes and 1xx are purely information requests.
You can check out all the HTTP codes at http://en.wikipedia.org/wiki/List_of_HTTP_status_codes.
If you never need to change your API, we all salute you for getting the API design right at the first time. Unfortunately, for the rest of us, APIs continue to evolve and we cannot breaker APIs callers to continue evolving our services. API versioning can be done via the request URL (where a URL contain details of the API version being involved) and users can toggle between versions of the API by changing a few fields of the URL or the request header. When using a request header to change the API version being called, make sure that when you add a new version, the older version that should be updated emit some kind of alert so that callers can know when a new version is available.
Keep that Help Ready
As developers swarm in to consume those APIs, be sure to have a good store for the developers. A developer portal will help navigate non-developer enthusiasts to samples that they can use as reference to build samples that call your feature. If they can code, you can point them to APIs; but if they cannot, you can provide them with ready-made samples and easy-to-understand instructions they can use. This will lower the bar of entry for your API callers.
Keep these tips and considerations in mind, and you can build APIs that developers will rejoice to consume.
In this article, we learned how developers can platformize their product by building APIs.
About the Author
Vipul Patel is a technology geek based in Seattle. He can be reached at firstname.lastname@example.org. You can visit his LinkedIn profile at https://www.linkedin.com/pub/vipul-patel/6/675/508.