API Design 101: The Basics (1/2)

This is a two-part blog where I try to explain APIs from a product manager’s perspective. In the first part, we will understand API basics. In part 2 of the blog, we will learn API product management and team organization.

What is an API?

Application Programming Interface a.k.a. API in simple terms is how different software talk to each other. They are used to expose services offered by the firm to both external and internal consumers. This in turn enables these API consumers to leverage data, functions, and applications to build new powerful products. Hence, APIs function as the backbone of any organization trying to promote the decentralization of innovation using microservices.

The Essentials

Now that we have understood what an API is and why it is important. Let’s look at some essential principles of an API.

The foundations of a good API are laid on top of these 3 core pillars:

Approachable

An API fosters innovation across a wide variety of audiences both internal and external. This makes approachability a quintessential quality of the APIs.

The APIs must be Intuitive & easy to understand, Discoverable, and Well-Documented.

For example: Naming the APIs is a very important construct. The APIs must be named using everyday constructs and avoid industry jargon. The archaic and sticky nature of names makes it even more important.

Flexible

APIs must be flexible in a way that they provide the right amount of data/output and give developers enough options both in terms of parameters passed and dev environments available.

Composable

Collectively, the API suite must be composable i.e. the consumers can use different APIs to create new services/products with ease.

The Design

If the strategy and designing process of the APIs is not done beforehand, it can lead to major roadblocks later on and limit their usability. Following are some best practices in order to avoid such setbacks:

Outside-In Approach

Coined as ‘Users first approach’, this principle stresses starting the design process from the users. Sometimes, this is also referred to as the ‘Working backwards’ approach especially at Amazon where the team starts with a press release, then FAQs, followed by wireframes, and then user manuals. This has a two-pronged benefit, first, you create APIs that will be designed with the consumers in mind and hence will have better adoption and second you communicate the product requirements across the org and cross-functional teams better. While designing the team must take care of both the direct users i.e. the developers and the end customers i.e. the users whom the developers serve.

Give it some time

Just like they say, ‘Rome wasn’t built in a day’, good APIs also need time. Spend enough time on designing, gathering feedback, and re-designing the APIs even if they are in the MVP stage. The team must dedicate time to ensure a good developer experience, develop the right SDKs, libraries and documentation for the APIs because APIs tend to be sticky and if not rolled out properly they may never be adopted. This implies the team must evaluate the APIs on the following parameters before they decide to launch it:

1. Simplicity, i.e. easy and intuitive to use
2. Composability
3. Backward compatibility, the users must be given choice on when they want to upgrade their API integrations
4. Predictability, the same input must repeatedly give the same output.

Iterations make an API perfect

The design process must also maintain a balance between spending time on API and the release speed. The APIs must be good enough to get good adoption and the teams must not aim for perfection in the first go. Constant feedback, market research, and data analysis can help teams to launch new iterations sooner and achieve perfection. This means that APIs are not a one-time job but an ever-evolving process that requires dedicated teams.

Reverse Conway Law

Conway’s Law states that organizations produce systems that mimic their org structure. We can use this law in reverse to create the API suite we wish. For example, if we wish to create APIs that are in line with our product offerings, we create separate API teams in each product.

The Finishing

Apart from the core methodology of executing API development, the following are some DOs that would leapfrog the adoption of your API suite:

1. Avoid using industry jargon in API calls
2. Nested JSON structures that follow the object-oriented approach
3. API structures that use Enums and not booleans
4. PATCH requests must respond with the modified object in response
5. Polymorphism in nested response structures by stating ‘type’ of the object and then its details

Loved this blog? Continue reading the next one, API Design 101: API Product Management.

Source:

https://cloud.google.com/files/apigee/apigee-api-product-mindset-ebook.pdf