Standardizing the Design of REST APIs
Consistent APIs are one of the keys to IT success. Some organizations have thoughtful integration standards, some have less elaborate. Anyway, an imperfect standard in use is much better than no standard. A standard which isn't actually used, is the same as no standard.
Does the standard work? If anybody needs to consume the API, he knows how to do that. It's not a project risk 😨, but a usual task ✔️. If anybody designs and publishes a new API, he knows how to do that. If this still works when you have 10, 20, 100 or 500 APIs, then your API/integration standards work fine. Let's focus here on REST APIs.
There are two types of standards:
- Public 🌍: we want to be consistent with the rest of the IT world, so we use them as much as possible. OpenAPI or JSON Schema fit into this category.
- Internal 🏠: we want to fine-tune areas which are not covered enough by public standards. That's what we do with e.g., API Design guidelines. Internal standards also say which public standards to use and where.
We have REST APIs, why additional standards?
REST is an architectural style. REST principles are too generic and broad to be a standard.
What to standardize
All parts of API offer space for creativity and inconsistencies. Let's go through it.
| Level | Description |
|---|---|
| API (top-level) | On the top level of API, we describe the API purpose, authorization, versioning, license, etc. |
| Operations | API has multiple operations to get the job done. E.g., the BankGround API contains operations to create a new account, make a transaction, etc. |
| Resources | Abstract objects managed by API. We use operations to create them, retrieve them or change them. In the BankGround API, the resources are accounts or transactions. |
| Messages | The data exchanged by API operations. Each operation may have request, response or error message. Messages represent the resources. See the createAccount operation and it's request and response. |
| Data objects | Building blocks for messages. Here we specify the properties of the objects and their data types (string, number, etc.) See the Schemas at the bottom of the BankGround API definition. |
Coverage by standards
OpenAPI specification covers all these levels, as illustrated in the picture bellow. The good thing is we only need one document to describe the API. On the other hand, it does not address these areas in detail, e.g., it gives you complete freedom how to structure your messages.
OpenAPI Guide
Besides the specification document, which is rather dry reading, there's a great OpenAPI Guide with simple explanations and examples.
JSON schema is a standalone standard, a language that allows you to annotate and validate JSON documents. OpenAPI specification heavily relies on JSON Schema on the data object level. Though, OpenAPI does not support full JSON Schema, but it's subset. The good news is that each version of OpenAPI gets closer to the full JSON Schema.
Note
In OpenAPI, you can define data objects by JSON Schema and later represent them not by JSON, but by another format, e.g., XML. While this is possible, I would not recommend that. The best match for JSON Schema and OpenAPI are JSON documents.
Using these two standards (or one, if we consider JSON Schema included in the OpenAPI), there's still a vast space for inconsistency. That's why organizations create internal API guidelines. The guidelines tell e.g., how to name the operations, how to build the data objects, which HTTP statuses should be returned by operations and many other things. You can write a document or describe your guidelines in machine-readable format. the best is to combine both of these approaches. Spectral Linter is one of the tools you can use to define your rules and validate API definitions against them. You can enforce them in the CI/CD pipeline.
As one of the best guidelines for REST APIs I would recommend is Monite API Style Guide, it also contains the linter rules.
Valuable input for the guidelines comes from your developers. Developers know the limitations and difficulties of the technology stack, mainly the generators, programs that convert the API definitions into the code (Java, Python, etc.) The developers should definitely contribute to the guidelines and be amongst its reviewers. They also come with the sober approach that not all the bells🔔 and whistles from the standards need to be included in the guidelines. Keep it simple is one of the main principles.
Let's standardize
With OpenAPI (JSON Schema) and internal guidelines you can set pretty good REST API standards and automatically enforce the rules.
Any other standards needed?
Maybe you want to create REST API with hypermedia controls, sometimes called Maturity Level 3 or by an ugly name HATEOAS.
You can start adding hypermedia links to your messages defined in OpenAPI. You may end up with a question: "Do I really need to reinvent the wheel 🛞? Somebody must have done this before!" You are right. The JSON:API or HAL specification may help you. You can use it as a standard, or get at least some inspiration.
Summary
Take OpenAPI specification and narrow its use by internal API guidelines. If you feel you are reinventing the wheel in some area, look for other existing standards.
Keep all that simple and understandable. Automate what shall be automated.