API Design

Designing API‘s is not only different from designing other software solutions but quite challenging.

* Consumers of the same API don’t intend to use the API in the exact same way.

* Changes to API’s once they are consumed are not possible.

* API Consumers have high expectations and can be critical of your design as they need to invest heavily in consuming them.

So given this hard reality of designing an API, where do we start?

Business goals, Data and Developer experience are the primary drivers of an API design process. Understanding these drivers and using them coherently, can not only overcome challenges but also provide a design methodology that can be reused consistently.

Business goals help understand the need for the design effort. Business goals are usually modelled and documented as part of the organisations API strategy. API Strategies are aligned with the organisation’s overall business strategy, providing direction that can ensure synergy of your design. Besides, an API strategy can help measure the success of your design for further fine refinements. Analysing business goals should be the first step in a design process.

API’s are empowering organisations to seamlessly, process and integrate data. Understanding the value proposition of an organisations data and data processes is key, to designing useful and usable API’s.  

The success of an API design is vastly dependent on ensuring its ease of consumption. Back your design with good documentation, and ensure your design conforms to industry standards. Even with a technically sophisticated audience, choose realistic designs over technical elegance.

Tool up

With the right tools, you can reverse even karma!

Successful API designers invest in adopting an API specification or modelling language such as SWAGGER, RAML or BLUEPRINT to build their designs. 

Using these tools that are fast becoming industry standards, can offer enormous advantageous, over a more traditional documented approach.  These languages can be used to auto-generate documentation, server/client code, automated testing and endpoint templates for IPASS solutions.

Documentation

An API’s success is profoundly dependent on its documentation, so beginning your documentation early on, at the design stage, can be beneficial.

As designing is an iterative process and is subject to change, updating your documentation simultaneously ensures minimum discrepancies between your documentation and the actual operation of your API.

Having documentation before the development and testing phases gives developers and testers a far better understanding of the API’s end use.

In addition, publishing your change sets along with API releases ensures consumers are aware of the exact changes made to the API. It allows them to decide on any further action that might be pertinent to them.

Versioning

Given the challenge an API poses that it cannot be changed once consumed, it should not lead to designing API’s for indefinite use, making them liabilities. Instead use a versioned approach to managing the expectations of an API and retire them at the end of their use cycle. This allows flexibility, making an API design more purposeful. 

Schema design

Be prudent with the design of the API schema, by getting as many reviews and perspectives as you can, before finalising the schema design. 

*  Consider which data resources may or may not be manipulated by consumers.

*  Start with the absolute minimum data elements and extend the schema by adding fields only when required because you can always add but not change or remove them.

*  Use consistent naming conventions for data fields ensuring they are self-explanatory

Infrastructure vs functionality

A host of features, such as security, paging, throttling, licencing is needed to support the core functionality of API’s. Often you have a choice of incorporating them yourself as part of your design. This could make the design quite complicated and problematic to manage. Alternatively, you could unburden yourself and speed up using third party services that have been purpose-built to manage this. Having a clear separation of core API functionality and its infrastructural requirements can make your design more efficient and practical. 

In the recent past, there has been a foray of middleware providers, providing a variety of these features. They are certainly worth exploring, before deciding, on designing and developing them in-house.

Complexity

Over time, an organisation’s offerings mature and grow. There could be use cases which require a complex orchestration of business rules involving the consumption of API’s. Instead of catering for this complexity in your design, consider building and providing widgets as part of the integration strategy. Widgets encapsulate complexities and provide consumers with a faster integration solution are logically the next stage in the maturing API’s.