API Design Best Practices and Design Principles

By | February 7, 2019

In one of my previous posts, I explained what API’s are and why API Management matters for an organization and why an organization should think seriously to invest in on-boarding some sophisticated API Management tool to better expose their APIs to the outer world and benefit from it. With API Management at the top, a significant point to consider for any organization is to ensure that best practices and optimal design principles are used in designing the APIs and associated back-end services so that It turns out to be a win-win situation for both app-developers and API-developers with least hassles down the road.

In this post, I will talk about some of the API Design Best Practices and API Design Principles that must be followed during API design and development to form a user-friendly and business-friendly API structure.

API Design Best Practices and API Design Principles

APIs Should Be Flexible

When designing an API to be exposed to the internal or external Application developers; requirements of the current developer base as well as potential future customers should be kept in mind and API should be designed and developed with utmost possible flexibility by ensuring loose coupling among the pieces and ease of modifications in future. APIs should be designed in such a way that any back-end fixes or upgrades have minimum or ideally no impact on the applications developed by the app-developers.

When designing APIs, it should also be ensured that potential developers with different set of tools and technologies and varying platforms should be able to use your APIs with same level of ease and user-experience.

One scenario of API flexibility is support for JSON and XML formats at the same time to give developers a flexibility to conveniently choose either of the two options for request and response formats when consuming your API.

Another flexibility option that you can consider is to expose both SOAP and REST variants for the same service so that developers who have subscribed to your APIs can decide based on their own expertise, available tools and technologies and organizational preferences that which of the two types of services should be used during application development process.


To introduce flexibility in your API design, you can opt for versioning of your APIs with each version corresponding to a specific type of flexible offering.

 APIs Should Be Well Documented

According to Albert Einstein, “If you can’t explain it simply, you don’t understand it well enough”. Likewise, if your API is not well documented, it is of no use!

For developers to get a clear picture of your APIs, all underlying methods, method capabilities, parametric details, request response patterns, possible faults and associated fault codes and any other details pertaining to your APIs should be documented without keeping anything unclear for developers for the consumption of your APIs and utilization of its exposed features in their applications.

Documentation of your APIs should be in user-friendly language and It should give your users a clear picture of the API specifications and user should be able to stand on his own toes after reading the documentation.

Any upgrades, versioning or any bug fixes to your APIs should be properly documented and communicated to the developer base to avoid any hiccups in the applications exposed by them to the end-users.

For the documentation in the developer portal; for developers to get a real-feel of the API, “Try It” type of options should be given for them to straight away test and try your API methods before they start implementing it in their products being developed.


APIs Should Be Secure

Developing APIs which will be used by the developers for diverse end-users, puts a greater responsibility on you to ensure that APIs are well secured with necessary security measures implemented. APIs should be exposed with no loopholes and authentication, authorization should be considered keeping in mind level of security and data confidentiality that your services and service users demand.

For data critical APIs and for any APIs demanding higher level of security, ensure that two-way (mutual) SSL is enforced. Other security measures for authentication and authorization like Access tokens, OAuth, SAML, Credentials based authentication and role based authorization should be considered as per your needs.

APIs should be thoroughly tested for any security flaws before they are made public and a regular check should be in place for any security loop holes to make sure no intruders are able to pass through.

With API Management tools in place, much of the security policies can be enforced at the gateway level which makes it easier to tackle with security level issues before the traffic reaches to the back-end services.


 Naming Conventions Should Be Followed

When designing and developing APIs, some standard should be followed for naming the resources to avoid confusions and conflicts. Developers should be able to get a smooth development experience with your APIs and names of your resources should themselves speak about their prupose of existence.

It is ideal to follow universal naming conventions followed publicly for REST & SOAP Services. URI structure, operation names, parameter names etc. should be following the same naming conventions for all the APIs exposed.

At a high level, just make sure that names should be simple, intuitive, consistent and user-friendly.


API Should Be Optimized for Response Time

The APIs that you will expose will get consumed by the developers in their applications which will then become available to the end-users. For end-users, response time of any service really matters specially for time-critical and data-critical applications. An API which takes longer to respond to user requests and blocks the session is never a preferred choice as end-users from varying type of devices expect to get their request fulfilled fast enough to increase the throughput.

While designing and developing back-end services for your APIs, ensure that there are no blocking code pieces or elements in your service and the service doesn’t end up with timeouts or faults too often. Services should be developed in fine-grained fashion with loose coupling with least underlying overheads for faster processing and better response times.

Even in fault/exception scenarios, your service should be designed to respond in timely manner with error response rather than blocking the user session.


Response Codes and Response Messages Should Be User-digestible

Back-end services are designed and developed by a pool of technical resources but It must be kept in mind that tool-specific or implementation specific technical jargon should be kept limited to the service boundaries and outer world should be communicated in simple and developer-friendly tone in such a way that app-developers who are utilizing your APIs are able to get well defined techno-functional responses from the APIs. For any API, response codes and response messages being returned should make sense and every response message should give developers a clear picture.

For example, in case of an error due to incorrect request structure by the user, app-developer should get such error code and message as response from the API that he/she is able to understand about any fault or exception that occurred in the back-end in case of a failure response and they should be able to retry with correct request later on. Response codes and response messages are aimed to help user (developer in API case) diagnose and resolve the issues if caused by them and to provide them necessary details if issues are caused at API/Service level.

Also keep in mind that target audience for APIs is not the end-user rather app-developers so you are not bound to introduce full user-friendliness in your request response structures but simplicity is still better to ease the development process for application developers with varying level of expertise specific to any programming language.

Response codes and response messages should strictly adhere to the API documentation as explained in the documentation section above.

I hope this blog post helps you at a higher level in understanding the principles and best practices that should be followed while designing APIs and back-end services. I have also talked in detail about API Management Best Practices in another tutorial on this blog. Feel free to comment below if you have anything further to say on this.


Ajmal Abbasi

Ajmal Hussain Abbasi is Integration Consultant By Profession with 13+ years experience in Integration domain mainly with TIBCO products. He has extensive practical knowledge of TIBCO Business Works, TIBCO Cloud, TIBCO Flogo, TIBCO Mashery, TIBCO Spotfire, EMS and TIBCO ActiveSpaces. He has worked on a number of highly critical integration projects in various sectors by using his skills in TIBCO Flogo, TIBCO API Management (Mashery), TCI, Tibco Designer, TIBCO Business Studio, Adapters, TIBCO EMS, RV, Administrator, TIBCO BE, TIBCO ActiveSpaces etc. Ajmal Abbasi has experience with MuleSoft ESB as well. Ajmal Abbasi is also experienced in the area of API Management particularly with WSO2 API management platforms. Ajmal Abbasi is also experienced in developing solutions using Core Java and J2EE Technologies. You can contact Ajmal Abbasi for Consultancy, Technical Assistance and Technical Discussions.

More Posts - Website - Facebook - LinkedIn - YouTube

2 thoughts on “API Design Best Practices and Design Principles

  1. Abhijeet

    Ajmal – I am little 2 wayed about your point for that API response message should be highly user friendly. We can try to keep it little techno functional but as finally systems are going to consume these APIs only status code like 200ok or ‘S’ or error code (111-ACC-NOT-FOUND) should be enough to get understanding by the caller that API call is a success or error.

    Anyways any validation for the data wherever possible and applicable should be done at front end rather than backend APIs.

    1. Ajmal Abbasi Post author

      Dear Abhijeet,

      The word user in case of APIs refers to the app-developers and idea is to keep the responses understandable and well digestible for developers who are undoubtedly technical but still it is important to keep the error messages less coupled to the back-end implementation specific jargon. E.g. if back-end is implemented in TIBCO BW (my favorite), application developer shouldn’t be getting error messages specific to TIBCO rather he should be getting generic and understandable messages.
      Anyways, the word user was slight confusing as it was interpreted as end-user so I have made the necessary updates for the said section.


Leave a Reply

Your email address will not be published. Required fields are marked *