Blog Post

API Economy is a pretty recent phenomenon where businesses have started seeing APIs as an extension of their businesses. While some businesses are API only like Rapid API, MuleSoft etc., other businesses like GitHub, Netflix, Google are extending them as another revenue channel. The growth of APIs has been exponential and similar trend we will see in the future.


APIs are nothing but a programmatic[automated] way to securely communicate between two applications [in effect two businesses]. Now since every company is trying to focus on what’s core to it and outsourcing the non-core part to other companies, API integration as a part of value chain fits in perfectly. You do what you do the best, and for other needs integrate the expert in that field, thus create a win-win situation and seamless customer experience.


Here I would like to mention few guidelines about designing APIs for your business.


  1. Understand the business first: Your APIs are a channel for your customers to consume the services you are offering. So, first list down what different services you want to extend and the business process around them. 
    Example: A bank performs services like account opening, giving account statements, enabling money transfer, creating a FD. This bank can design a business process flow like first a new customer will open an account by submitting required documents and bank will verify them. Once verification process is complete bank will notify if the customer is verified or not. 
    In this simple flow bank can create one API to submit on-boarding documents and push verification status with details to a callback URL [given by the developer] or bank can extend an Application status API to check the verification status. Similar flows can be designed for other processes and then APIs can be created to support that flow.

  2. Simple design is the best: One of the main problems with APIs is that their structure is pretty complicated [unnecessary nesting and inconsistency] which leads to long time to integrate and use them. Keep your request payload and header structure intuitive[as similar as possible payload for each API], consistent[response always has same structure] and use JSON as the exchange format unless you have strong reason to use XML.
    You should use standard HTTP response codes [201 created, 403 forbidden, 202 accepted etc.] so that developers who are already familiar with it can quickly understand the structure and new developers can learn something which they can use elsewhere.

  3. Think about security: This I can’t stress enough. Since developers are mostly focused on coding the APIs the security part sometimes can take backseat. But since APIs are programmatic which means they work at lightning speed, a malicious element can severely impact your business in no time if it exploits a loophole in the API.
    Enable rate limiting, I.P whitelisting, ephemeral tokens, scan for any authorization [data access] loopholes. You should go for regular security audits.

  4. Enforce Validations: Your APIs should guide the developer if the submitted data has any inconsistency. The response should help to debug quickly so that time to integrate is reduced. You should try to cover as many edge cases as possible. Validations also act as the first layer of security.

  5. Design for scale: APIs growth is most of the time exponential if what you are building is something for which there is demand. So always think of scale [what happens if you have million customers] when you are designing them.

    Use elements like pagination for long list of items, say transactions of a customer or use callbacks instead of polling where you want to communicate with the customer. It will make life easier once you hit scale.

  6. Create Stellar documentation: One of the differentiation of great API companies like has been their excellent documentation. They guide the developer about different modes of integration, the transaction process[by nice graphics] and have code snippets clearly showing request and response structure.

    All the fields in the request & response are described, data-types listed with allowed values. They also show the error scenarios so developer can handle the error cases as well.

  7. Version your API: Today's businesses are dynamic. So always version the APIs so that you can roll out new features in new version and also keep supporting the customers who are already live on older versions, giving them time to change APIs.

So, if you create very easy to integrate APIs, extending services that solve major customer needs, it can give a major boost to your business.


For companies which are solely API based there is no excuse but to follow best practices to create an experience that developers love, thus propagate the word and these companies don't experience issues as they scale.

Learn21 conducts an online Boot Camp for web development. If interested you can check the details here.