API Design Review Checklist: Questions Concerning the Developer Experience (DX)

This post lists 25 questions to ask when reviewing the Developer Experience (DX) of an API. It groups them by the four DX pillars (functionality, stability, ease of use, clarity) from “What Is DX?” by Albert Cavalcante, elaborated upon in Chapter 1 of “Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges”.

Pillar 1: Function

Form follows function, as architects, designers and engineers in the real world taught us. So let’s start with the function pillar:

1. Has the goal of the API been established? How about its visibility (public, community, solution-internal) and direction (frontend-to-backend, backend-to-backend)?
2. Can the API design be traced back to a functional requirement or integration need? Can use cases or user stories for the API be deduced from the API specification?
3. Is the role of each endpoint clear? What is it responsible for: processing, information holding, asynchronous data transfer (between clients)?
4. Does each operation have a dedicated responsibility (write, read, read-write, compute)? Do these operation responsibilities collectively meet the API client wants and needs?
5. Does the data contract of the API (i.e., its request and response message representations) contain everything that is needed, but no more? Is the nesting of the message structures justified by the data usage profiles and domain semantics (i.e., as deep as needed, as flat as possible)?

Pillar 2: Stability

Stability has both developmental, operational and managerial facets:

1. Does the runtime behavior stay the same as the API provider moves from developer desktop to integration test to system test to production (on premises, in the cloud)? Does the deployed API implementation survive outages, for instance loss of backend connectivity?
2. Does the actual Quality-of-Service (QoS) match the specified one? Are realistic service-level agreements in place?
3. Do the unit tests cover the entire scope of the API? Are they run every time the API implementation is built and deployed? Does this happen in an automated fashion?
4. Is compatibility preserved when new releases are deployed? If not, are Version Identifiers present? Is Semantic Versioning applied?
5. If Software Development Kits (SDKs) for different client programming languages exist, do these SDKs expose the entire set of API features? Are they documented well, robust and stable?

Pillar 3: Ease of Use (including Simplicity)

If you know your audience, you can speak its language and design for it; if not, generality has to be invested in and/or assumptions have to be made. Either way, an API should cause as little learning effort as possible:

1. Is the API designed for a specific developer audience? If so, are the preferences and constraints of this audience known? Do its requirements justify the tradeoffs made for the API design decisions? Are the wants and needs of the target audience reflected in the API description?
2. Is the API designed for a general, possibly unknown developer audience? If so, is it broad and deep enough to satisfy varying user needs? Are the provided variability features easy to configure?
3. How long does it take to read through the ‘getting started’ information and get the API client examples to run that are part of the API documentation?¹ Is the related usability requirement met, hopefully specified in a specific and measurable way?
4. How long does it take a member of the target audience to code and test the first own API client, a Minimum Viable Product (MVP) for API usage?
5. Do sandbox environments exist for API testing? Do these environments come with pre-loaded sample data?
6. Are error situations on the technical and on the business domain/application level reported in such as way that developers are able to code client-side error handlers?

Pillar 4: Clarity (and Consistency)

API client developers usually do not appreciate surprises, and they would like to focus on their code rather than any intricacies of the APIs they use:

1. For all APIs: do the names of API elements speak the Published Language (a subset of the Ubiquitous Language) of the domain? Are the syntax and semantics of all request and response message elements explained, are sample values provided? Are acronyms that would obfuscate the meaning avoided?
2. For HTTP APIs: has one of the REST maturity levels been decided for, does this decision make sense and does it become apparent in API design and documentation?
   • Is the URI structure sound and easy to understand (level 1)?
   • Are the HTTP verbs used properly (level 2)?
   • Do links drive the application from valid state to valid state dynamically (level 3)?
3. Are the pre- and postconditions for each operation defined, for instance the need for clients to authenticate and authorize?
4. Are architectural properties such as idempotence, statefulness and valid conversations over multiple API calls disclosed? Are they adequate in the given domain context?
5. Are the terms and conditions, including API pricing and rate limiting, understandable and acceptable?

Also Important: Operator Experience and Maintainer Experience

We identified the need for a decent operator experience (“OX”) in our book. And we can add evolution and maintenance to the discussion as well:

1. Is the API usage monitored? Do the monitoring data steer the API evolution?
2. Is site reliability engineering practiced? Are systems management patterns such as Test Message applied adequately?
3. Are the service-level agreements (if any) adhered to?
4. Is a lifecycle management strategy such as Limited Lifetime Guarantee or Two in Production in place? For example, are unused API parts (e.g., endpoints and their operations) deprecated and eventually removed?

Note that we already asked several related questions under the “Stability” pillar above (DevOps calling!).

Other Checklists and Review Advice

A Google search for “API review” does not yield as many results as one would think (at the time of writing). “API design review” gives more. A few of the online resources covering our topic are:

• “How to conduct an API design review” by James Higginbotham²
• “A Checklist for Your Next API Design Review” on the Nordic APIs blog
• “REST API Checklist”, specific to/for HTTP resource APIs³

Wrap Up

This post collected 25 questions about API design. Note that I focused on questions about the DX of an existing design; questions that have to be answered to start and justify a new design were only touched upon.³

If you answer “yes” to all questions, your API probably is in good shape. A few “not applicable here” might be ok too. Any “no, but I see the need” answer might be a review finding. 😯 🤔

The process and patterns in our book show you how to avoid or minimize review findings. And our emerging “Interface Refactoring Catalog” collects knowledge on how to get rid of related design smells including usability issues; the quality concerns that we compiled can also get you going with the catalog.

I hope you found this post useful. Let me know.

– Olaf (aka ZIO)

This post is also available as a Medium story.

Acknowledgements

Thanks Gregor for bringing the topic up! My co-authors contributed input and/or reviews of drafts to the checklist.

Notes