Web APIs (Application Programming Interfaces) are quickly becoming the de facto integration model for IT systems. Key promises of web APIs (e.g., reducing development cycles within an organisation, fostering collaboration within the partner ecosystem, or monetising APIs from external use by third party developers) all rely on simplifying efforts for developers so that they can get stuff done with as little overhead as possible.
To that end, designing good web APIs means taking a product-centric approach.
API products distinguish themselves through a) key functionality, and b) ease of use. For functionality, it’s about providing access to special data and services, doing so cheaper, with better security, or with guarantees of service stability and quality of service. Differentiation around ease of use involves making it easier for developers to discover the APIs needed for what they want to do, to understand how to use said APIs, and then to gain access to begin using them. The mark of a good API is that it is distinctive in its functionality and benefits and thus attracts developers, which in turn makes an API program successful.
Distinctive functionality and ease of use manifests across a number of dimensions that include terms of service, design, support, and evolution. For each dimension, the question lies in weighing the implementation and complexity against the value the differentiation contributes to allow the developer to get things done.
Terms of service help developers determine the viability of APIs against their use cases before they invest time, effort and cost to implement. Some ways to customise terms include the following:
- Offer attractive cost models
- Provide added service levels supported by implementing more secure, highly available, and scalable architecture
- Distinguish terms based on the number of API versions maintained and when to depreciate: the trade-off lies between offering a large number of bespoke versions that better fit the individual needs of the developer against added the complexity to operate and manage
Design uses terminology and technology that developers understand, so it is easy for them to adopt the APIs. Web APIs already start with well-understood standards like API verbs (get, post, put, delete), formats (JSON, XML) and Internet protocols. Augmenting APIs with further terminology simplification used in requests and responses are easy for developers to analyse and understand. For instance, instead of a single catch-all service that captures all address nuances such as military designations (APO, FPO, DPO), rural codes, or country specific details, it is possible to separate the functionality and minimise the details developers need to know (e.g., the common format containing street, city, state, postcode). The key message: API design is good when it focuses on the perspective of the developer and makes it easy for the developer to understand.
Support the developer community via a developer portal that enables self-service on-boarding for discovering and gaining access to the APIs. It is not enough to create a registry of APIs because the developer might need to access a set of APIs in a particular order. For instance, to successfully place an order, it may take a number of API calls: creating or verifying an account, validating the correctness of the associated address, calculating the costs, processing the payment. Rather than a list of APIs, associate a carefully curated set of APIs organised around what the developer needs to do (in this case, placing an order). And then help the developer use the APIs to:
- Embed an interface for live exploration of the APIs against a sandbox environment
- Allow immediate provisioning of test access
- Provide sample code and clients that the developer can edit and use
- Effort paid to providing self-service support helps the developer get things done
Evolving the API program requires continuously revisiting and refreshing functionality to meet the needs of developers. Understand what use cases are working, identify heavy and light users. Gradually introduce a new feature to a set of beta users among whom its adoption indicates general success at scale. Troubleshoot operations across apps, clients, network, API management gateway, and backend resources. Monitor and apply analytics to evolve API functionality, which in turn ensures the continued support for developers.
Understanding API differentiation across these dimensions is critical in enabling the developer to do what he needs to do and to do so efficiently. Consider a goal where a developer should be able to understand an API in 3 seconds, identify an entry point in 30 seconds, and access and use in under 3 minutes.
It may be true that the use cases and users of web APIs are often intentionally left open-ended to foster innovation and collaboration, but that doesn’t mean that web APIs can be created in an ad-hoc fashion or via direct exposure of complex service oriented architecture (SOA) services. The web API cannot be a by-product of directly exposing existing backend services; else it fails to fulfil the needed functionality for the targeted set of developers. Or an approach that tries to address all needs is in danger of including too many details that results in confusion or of lacking the required differentiation needed to drive developer adoption. On the contrary, designing web APIs requires added discipline in order to expose the right set of functionality in a format that will appeal to consuming developers.
Start with evaluating “what is important for a developer” by considering “who he is” and “what he is trying to do.” For example focus on enabling access for developers from a partner organisation may result in API design with terminology different than what one would provide internal or third party developers. While the same API may ultimately also serve useful for other groups or use cases, the initial focus ensures that the resulting API fulfils the requirements so that the target group of developers will want to use it.
The API’s self-service model empowers developers with efficiency and greater choice as to what data and services to use. Rewards and opportunities created by web APIs come from enabling the developer. As such, designing an API program with the developer in mind is the key to success. With APIs, the developer is in the driver’s seat. A good API is one that considers things from the developer’s perspective - the success of an API program depends on it.
Posted by Teresa Tung, Manager, Accenture Technology Labs