API Design: Tabs versus spaces

With Thanksgiving behind us, the holiday season is now in full effect with lights on houses, jingles on the radio and relentless commercials reminding us we need to buy gifts for our loved ones. It is during this time of year when I drive past the giant USA pet stores, not you, but rather Petco and PetSmart that I’m reminded of this slogan: “A dog is for life not just for Christmas.” Now, what if we were to change the word “dog” to “APIs”? 

Once an API is made available, either internally or publicly and it is being consumed by a client application, it becomes a contract that needs to be upheld by the API provider. As with any contract, it must be followed to avoid a breach with the consumer. In other words, as a developer, one cannot make wholesale changes to an API because this would break your consumer’s application.

As a consequence of maintaining this contract, the ability to innovate and evolve the system becomes constrained. It is important to spend time on design upfront in order to mitigate the risks these constraints impose. With proper design, responding to changing needs can still be achieved while maintaining the integrity of the API contract. 

This blog provides some tips on how to ensure that you have successful design reviews prior to the release of the API contract.

1. Avoid “Tabs versus spaces”

Today, during code reviews, code formatting discussions never come up. There is no debate on tabs versus spaces or where to place parentheses, etc. This is because automated linters and code formatters identify these issues before the code makes it to a pull request. So they’re resolved early (and thank you gofmt). Linters are tools that analyze source code to flag programming errors, bugs, stylistic errors and suspicious constructs. There are a number of linters available for APIs and some of these can be extended to include within your organization’s own “standards.” Linters should be applied early and continuously in the design of your API so that your API is adhering to your organization’s API style guide.

2. Avoid bikeshedding

Parkinson’s law of triviality (bikeshedding) is an observation about the human tendency to devote a great deal of time to unimportant details while crucial matters go unattended.

During reviews, teams will debate extensively the names used in APIs for resources, while the complex issues remain ignored. Issues like: How the API they’re designing will address the use case for the consumer in an intuitive and natural way; if the API is already live and being consumed, what are the implications of a breaking change; or how should the API be evolved from the existing version to a newer, etc. This particular step is more nuanced than a simple lint, but careful consideration of the above, during design, will save pain in the future.

3. Don’t forget the ’itties

Recently, I was at a customer site reviewing one of their APIs. The API was beautifully crafted, addressed the consumer’s use case, adhered to the corporate API style guide and addressed security access via JWT token per transaction. However, in this particular API, the JWT was the same in each message and the token contained in the JSON payload, which was getting stored in the cloud. All this hugely drove up the operating costs of API as it added addition I/O overhead on the network and for storage.

This reminded me of the discovery American Airlines made 30 years ago, they determined that eliminating one olive from each passenger’s salad plate would reduce costs by $40,000. Removing the JWT token from each message and replacing it with traditional session and session store significantly reduced I/O costs of the API.

American Airlines saved $40,000 a year by removing one olive from each salad in first class.

Nonfunctional requirements (NFRs), describe system attributes such as security, reliability, maintainability, scalability, usability, operating costs, etc. and need to be considered in the API review. To quote and learn from the Phoenix Project: “You get what you design for… your peer in development is spending all their cycles on features, instead of stability, security, scalability, manageability, operability, continuity and all those other beautiful “itties.” 

4. Know your ecosystem of APIs

Your API consumers do not care about the history or how your organization is structured into separate teams. The internal or historic origin of where the APIs have been developed should not leak into the API contract. It is not uncommon that APIs from a single API provider will contain objects that to a consumer represent the same logical context, but as the APIs have a different heritage, the objects have a different schema.

For example, an entity that represents the “end-user” could be represented in different APIs as “customer” or “client” or “consumer” and each of these objects with different field names but with the same value. During the review, it is important that an API uses the same naming or terms for the same concept that are already in use in other APIs in the organization. It is important that a catalog of an organization’s existing APIs, resources and models are available to cross-reference during the review.

5. Air gap between contract and implementation

In your development cycle, you should have a clean separation between the review of the API contract and the implementation of the API itself. If you implement too soon without the appropriate review, then it is harder to change. The best approach to avoid mistakes between the ideation of a contract and its implementation is analogous to the UI design workflow. The mapping to UI design workflow, which is an established practice in most software development teams, works well when you transpose the players.

If an API is analogous to the GUI for developers, then the contract is a wireframe and the API consumers are UI users validating what is presented in the wireframes. Would you ever go from an unreviewed wireframe and straight into implementation? The simple answer is “not if you want to keep your job”. So, following this design workflow approach, help ensure that once the contract has been refined and is delighting its API consumers, then implementation can start. 

6.  Reward reviewers

API design review is a human process that again makes it nuanced and sometimes arduous. This review requires human discussion around the API and its usability and overall effectiveness. Humans, like pets at Christmas in life, like to be rewarded and acknowledged.

As the review is so important to the success of the API, it is important that you reward and acknowledge the reviewers. You can not claim to value API reviews if you do not reward the effort and time of developers, architects, product managers, and other stakeholders spend on the task. Be creative here, you don’t have to sell the farm, but there are plenty of fun things that you can come up with to make the reviewers feel the value of this accomplishment.

7. Rubber stamping

Rubber stamping occurs in politics whereby officials approve legislation without careful thought or due diligence- Stamp, next, stamp, next... etc. In software development, rubber stamping occurs when a PR is accepted and merged without giving it the necessary review. “Oh, this is from rock star engineer – auto-approve.” The same human behavior can occur in API reviews, “Oh, this was created by the team that produced the previous successful API service. Approved.” Remember that the API you are rubber stamping because the previous API was “good” is due to the fact that they did not previously rubber stamp. Put aside all previous judgments and look at the API contract as a consumer and assess it solely on its merits of addressing the consumer’s use case. 

8. Bring the right people to the review

The best reviewers of your API contract will be those that need to consume the API. If your API will be private and you’re developing microservices, then the reviewers are the teams developing other services in your mesh. If your API is at the edge of a domain boundary (department, organization, etc.).

Then you need to cast your net wider to find your consumers. They are harder to find and engage with as often they are committed to their own deadlines/goals. It’s important that you find and engage with them early because a review without a consumer’s perspective is of minimal value. You need someone in the review who is focused solely on the use case/jobs of work to be done and is not distracted/biased to how the solution would be implemented. 

READ MORE: Learn the difference between microservices and APIs.

If you have an API Center of Excellence, then take advantage of them as they can advise on best practice, KPIs and have knowledge of the API landscape in your organization.

The best API review should provoke discussion on the experience that the API will provide to the consumer. Following the recommendations above hopefully you won’t end up with an API that is like  “a house built by a child using nothing but a hatchet and a picture of a house”: