A Simple API Design Walkthrough
How to prototype an API before you code
Jun 13, 2019
The software your company creates is made up of many APIs and microservices. While each has its own purpose, it should not have its own style. Yet, with different teams working in tandem on many projects, divergence is natural. It’s also confusing to developers using your APIs when endpoints are named differently and field names use different formats.
Just as an OpenAPI document can be a source of truth, an API style guide can keep your organization producing APIs that feel like part of the same whole. You don’t even need to slow your progress to get these details right. Instead, with a clear style guide and open source tooling, you’ll be able to streamline your API design, documentation, and testing.
Many organizations maintain design style guides. These documents detail the visual decisions already made in terms of colors, typography, sizing, and layout. A design style guide gives collaborators a shared vocabulary, which they can use to build consistent visual designs.
Similarly, an API style guide keeps your team on the same page. Consistency within a single API is hard enough. When your organization publishes dozens of services, a consistent API design style is imperative.
Without a defined style, developers are left guessing at naming conventions, field formats, and HTTP methods. For example, when supporting pagination, should you use
p in the query string? (Or is it something else entirely?) Your hypermedia next and prev headers could help answer this question, but it’s worth aiming for consistency, even when there are other methods to communicate a decision.
Teams building APIs want to remain consistent with each other. And developers consuming APIs will likely be using them from multiple teams. Your API style guide can bring harmony to your APIs, the teams that build them, and those that consume them.
Some large organizations, such as Google, have made their API style guides public. In your case, you’re likely putting together an internal guide. Therefore, the needs will be specific to your organization. Start with some areas where you’ve seen inconsistency within your APIs. Solicit contributions from across the organization on what should be included and why each style decision was made.
With REST APIs, you’ll likely want to ensure you organize your API around resources. Even with this best practice explicitly stated, there are a lot of API design decisions left to make:
You may find even more areas to include in your API style guide. Committing these decisions to a written guide will help you communicate it to the rest of your organization. However, you need to include API style checks in both your human and machine processes to help maintain consistency.
In the API Design Guide, we cover three high-level tenets of API design:
Each of these principles can be amplified by a style guide. In particular, including a collaborative review in your new API process will help the entire team check the design against your style guide.
In many companies there is an architect or even an architecture team. If this group exists, it can be a driving force behind a style guide. It can help maintain it and may have its own process for enforcing. That said, consistency is up to an entire organization. Each API project could include an “API stylist” who helps the team review designs against the style guide.
When you bake these best practices into your process, you make it easier to maintain consistency. While human checks are important (and part of a collaborative design), you can also turn to automation to help enforce your style guide.
You can further engrain API styles in your organization by including style checks in your continuous integration pipeline. Many of the decisions you make in your style guide can be described in a machine-readable manner. Stoplight’s Spectral project is built on top of the OpenAPI or Swagger description of your API. Spectral includes JSON validation and linting, which allows you to run style checks against Spectral rules automatically.
The simplest checks you can make are validations. You can use Spectral (and other JSON validators) to ensure your API description matches the schema of the OpenAPI specification, for example. This will catch mistakes with curly brackets, missing fields that OpenAPI requires, and other issues within your JSON. You’ll want a valid OpenAPI document so that your other teams can make use of it, such as for generating documentation or testing the API.
Another level of granularity is to look for fields within your OpenAPI document that you want present in every description your organization produces. Parameter descriptions, for example, aren’t required by the OpenAPI spec. However, they’re extremely useful for developers consuming your API. A JSON validator will see missing parameters as valid, but your style guide would suggest it should be required.
JSON linting rules within Spectral allow you to require a field be present and non-empty. In the parameter example, you would be able to raise an error, which would alert your team that the API needs to be updated to match the style guide.
You can also include more complex rules. Capitalization and punctuation styles can be described as regular expressions. Ensure your field names are formatted like you expect:
Any style checks that be written as a regular expression can be used in Spectral. And if you want to go more advanced, you can write your own custom functions. There are more details and community interaction in the Spectral repository.
When you share an API style guide throughout your organization, you encourage consistency within and across your APIs. You’ll build a better developer experience internally and with partners. Once you have an API style guide, work it into your software processes, including automated checks that keep everyone on the same page.