I’ve been thinking about API linting lately, partly because I work on a tool for API linting in my day job, and partly because I get quite a lot of questions from teams wanting to improve their API quality. The “best” ruleset depends entirely on your context, where you are in your API practice journey, and how much you want to invest in the API in question. I typically use a 4-levels model of API linting readiness, and I’m sharing them so that you can find yourself on the map and see where you might go from here.

This post is part of API Futures 2024, a series of posts by different contributors focused on the challenges for this year. My big wish is for everyone to find API tooling and configuration that fits their own context, which is why I’m publishing this linting levels post as part of the event.

Level 0: A valid API description

This sounds basic but a surprising number of public APIs either have no API description, or their OpenAPI description is actually invalid in some way. It may well work with the tools used in the producer organisation, but unless you supply a file that works with all other tools, there are limits to who can use and interact with your API.

Add some unopinionated validation to your CI workflow, and make sure that anyone who works on your API can also run those tools locally while they’re making changes – and you can graduate to the next level immediately :) Redocly has a rule for linting against the specification which is a great starting point (other API linting tools are available!). For the next level, there’s a great ruleset in the Redocly CLI Cookbook that you can copy and paste into your own projects; it aims to catch the things that match the declared data structure of OpenAPI and yet make absolutely no sense in the real world!

Level 1: Meets basic standards

Every API probably should have its own set of basic standards but I typically ask about the API linting rules that are already in place, such as:
– are there checks that security has been declared on every endpoint?
– is there useful metadata, such as a license and some contact information?
– does the API follow a design, such as RESTful API design, and how clear is that from the OpenAPI description?
– are consistent data formats used, such as cents (or equivalent) for money, ISO format dates, standard scientific units for measures?

Having some sort of API design, with some level of data handling, some supporting metadata, and some security practices in place is a level 1 API. Some APIs only need to be at level 1, such as a service with one or two endpoints that handles something non-critical such as newsletter signups. Sure, this API could be brought to a higher API standard and that could be enforced by tools and linting. But not every API needs the same level of investment or must comply with the same standards. Within an organisation, have a few defined levels, and make clear which APIs meet which standards.

Level 2: Has a consistent interface

There are few things more irritating than an inconsistent API, and yet a deeply consistent API interface is essentially an invisible feature. Users will very quickly feel comfortable and be productive using your API platform, but not being irritating is rarely given as customer feedback! So what are the ingredients for this developer happiness level of API standard? You can think of it as having two main elements: the philosophy, and the mechanics.

The mechanics is the simplest thing to get right. It means using plurals (or not), absolutely everywhere. Always using exactly the same variable name to refer to the same data, wherever it is used, and validating that data exactly the same way in both request and response for every endpoint. Having endpoints that are consistent in their shape and depth, and keeping common parameter patterns for features such as filtering or pagination the same everywhere. Adding linting rules to an existing API for this level of API standard can be quite tough, but add the rules you want to follow, with exceptions for any existing/legacy endpoints that aren’t compliant. Enabling the checks on the API, and acknowledging the parts that are known and shouldn’t fail the build, means you can automate the checks and add no more violations! The ignores list can also serve as a to-do list for things to work on, either by making backwards-compatible changes or to revisit if a new API version is in the works.

The philosophy part is a bit more difficult to think about but building on prior art in your APIs, for example by following established RESTful API design practices very tightly and adopting other standards that are already known and accepted. This approach means you don’t have too many decisions to make since you’re following existing and established standards, and the ideas may be familiar/supported by the users/tools that access your API. I particularly recommend looking into Hypertext Application Language (HAL) if you include links in the resources you return from your API endpoints, and RFC 9457: Problem details for APIs (replaces the better-known RFC 7807).

Level 3: Is a joy to use

We don’t describe developer experiences as “joy” often enough, but a really great API description definitely qualifies. If your API is your flagship product, or drives a lot of business value that is realised by strong integrations – this is the level you want to aim at. What’s funny about these top-level APIs is that their actual API design isn’t much different to the earlier levels, however the implementation and supporting materials are the special sauce.

To produce an API at this level, the API governance expands into a more holistic view of the API and what really makes an API experience joyful. This can be achieved with rich OpenAPI descriptions, and supporting documentation as the main pillars. I think there’s also an element here of discoverability, and that this aspect will only become more important in the future.

Enriching OpenAPI descriptions can take many forms. Make the most of the description fields; these support Markdown so don’t be afraid to add links, lists, or whatever else would help the user. From the very top level, where info.description sets the scene and purpose for the whole API, through the individual endpoint descriptions and down to the individual parameter and schema fields, the descriptions are the magic sauce. Explain not just what the thing is, but also what it does, and why the user would want to do that. Enrich also with meaningful and illustrative examples, using (culturally varied) example data that represents something a user really would be doing, rather than “foo” or “bar”. A project name could be “holiday_planning” and an email address “[email protected]”, and using values like this does make a more successful and happier end user.

The documentation is not just the reference documentation either. I haven’t seen linting rules for this, so perhaps it’s a little out of scope, but adding meaningful onboarding documentation or getting started guides, and tutorials for the most common tasks in an API are both excellent additions that make a good API into a great API.

Make your API next-level

Don’t be put off by API standards tooling that comes with big opinions of its own. Reflecting on what your API needs, and what your organisation can support, will help you find which level you are on and where you want to be and set your API projects up for success. Tune the API linting rules to get the support you need, but don’t be afraid to turn things off that aren’t important to you! All the tools come with default rules, but every situation is different so take the time to adjust it for your context rather than gritting your teeth and dealing with someone else’s ideals.