API Design Best Practices and Design Principles

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.

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.