API Centric Design - Key Design Principles

Some of the design principles that one should consider while embracing API centric design approach

Documentation

Documentation is a key principle of API design and development. Please keep in mind that the developers are the users of your API; therefore, the documentation should be the paramount deliverable item of APIs. They need to be detailed in every aspect whether you call it a contract definition or developer guide, it needs to be easy to understand and simple to use. Keep it up-to-date and eliminate outdated items. There are tools available such as Swagger that simplify the complexities and techniques involved in document writing.

Content Negotiation

There should be a provision for flexibility in terms of technology and usage preferences, which allows developers to prefer an option that best suits them. Greater flexibility helps in accelerating the adaption of your APIs. It includes:

• Supporting multiple formats (media types). For e.g. json and xml formats

• Understanding developers’ technological preferences, and support if possible

• Adapting the preferred standards and specifications

Compatibility

It is important to be compatible with each consumer and changing business needs. It is also essential to version each API release and document each changelog, so that the behavior of the API remains consistent, thus keeping the various consumers unaffected and stable. Do not forget to deprecate the older and unused versions.

Adaptability

The APIs that are published must be easy to understand and simple to use. There should be a provision for developers to try-out your APIs before they see benefits and start adopting them for production use. This should help to ease onboarding of third party developers and partners. As the saying goes, “The first impression is the last impression”, and hence chances are high that developers will adopt your APIs if they find them easy to implement. A community for trial-users and enterprise support for production-users will greatly enhance the adoption of APIs.

Security

Security is the basic need of any application design and development. Moreover, when securing the public APIs, the complexity grows in terms of design factors. Some of the key factors to consider are:

• Always use SSL for public/protected APIs

• Use tried and tested authentication schemes

• APIs are stateless and and eaach API can be called many internal/external services. Hence it is essential to authorize each caller, be it trusted service or an external service, to each resource

• Always encrypt data in transit and data in rest

In my next blog will be on the Guidelines and Best Practices followed as industry standards for API development