Share:
.svg)
.svg)
This blog is based on a talk presented at APIMatic’s meet-up in San Francisco earlier in the year.
API specifications have become a crucial part of the API life cycle, acting as a gateway to better design, documentation and tooling for your API.
Due to the growing popularity of API specifications, more and more organizations are moving towards spec-driven development. In this process, API are designed before built, so that any flaws and inconsistencies are recognized early on and fixed before the development. The approach ensures you stay on budget and avoid snags that can come from miscommunication.
While a spec may ensure that there are no hiccups while developing APIs, the document itself is prone to inconsistencies and errors. Multiple stakeholders including developers, product owners, and technical writers contribute to the spec, and with all of them bringing in their own flavor and style, it often ends up looking like a mess.
Moreover, a spec is more than just a design artifact, it serves as a gateway to various API tooling throughout the API lifecycle. Many of the API Design, Management, Testing, Deployment, and Documentation tools today take API Specifications as input to work on the API, and unless free of flaws and contradictions, a spec can never be rendered in an efficient or effective manner.
It’s therefore essential to have a set of guidelines to ensure the document remains free of conflicting styles and formats and is produced in one cohesive manner. This blog will cover a few of these guidelines and practices that you can follow to achieve consistency across the API Specification workflow while keeping it functional and agile.
1. Create a Style Guide
Often organisations have a style guide for designers and writers to follow when producing branding content and material. In a similar fashion, all API teams should develop a style guide for writing API Specifications. And it should be enforced as a uniform practise throughout the organisation. The guide should recommend what sort of conventions and practices are to be used when contributing to the specification.
For instance, often it’s unclear if:
- Schemas should have examples
- In-line schemas are permissible
- Operations must have descriptions
- Parameters and responses restricted to certain types or numbers
Similarly, in many more cases like that, contributors whenever in doubt, just work with a style they are used to or comfortable with. The easy way out is to standardize these practices, and recommend a way which guides contributors from all departments to make additions in a uniform manner.
To ensure that the recommended practices are being followed, and no conflicts make through to the actual document, validators should be set up that verify if the addition is aligned with the recommended style. This can be executed with Linters, a popular linting tool for specs is “Speccy”, which takes your custom rules and runs the specs against it, validating it against those rules.
Building validation into the CI/CD cycle further streamlines the process, so whenever updates are pushed to your API, they first go through these checks so that nothing of varying nature is added to your specification.
2. Promote Visibility and Reusability
Another common practice and really a nice one is to publish your API specs to Version Control for across board visibility. Make them available on a master repository and create a pull request mechanism, allowing nothing to pass to the central repository without a review, while still allowing contributors to view and make use of each and every contribution.
A big part of the specification is the schema itself, many organizations today are using JSON schema to define those specifications, even though OpenAPI has a schema that is subset of JSON schema, but JSON schema has very good tooling around it and in many more numbers. Defining models in JSON schema would make the spec very versatile and open-ended.
You can again use Speccy to convert JSON schema to OAS schemas. This would allow you two things:
- Keeping your schema separate from API specifications
You have a new team and they want to use the same object the other team is using, from going to actually write it from hand again, and having discrepancies, you can use the same schema, just refer it in your spec.
- Validating API specifications
With JSON Schema Linting, you can write better tests. Resulting in better validation of schema.
And for every artifact you are creating, schema or the spec, version them, so once your program scales, you know what version your API team is dependent on.
3. Separate API Design from Documentation
A specification is normally maintained by API developers, they are the people responsible for putting in what the requests are, what the endpoints are, how the responses would look like, basically the people turning an API into reality, but there is also a team of tech writers who work on the spec to add documentation, sample code, guides and tutorials, and all sort of help material to make sure that the API human-readable and usable.
To allow both the development and documentation team to work simultaneously, you can maintain documentation and tutorials as a separate project while the developers work on the spec to make changes to design
There’s a concept of overlays, which has already been introduced in RAML and is still being talked about in OpenAPI Spec, and we here at APIMatic are actually building this out in our own format. What Overlays essential does is allow separation of these two concerns, letting your tech writers work independently so that any drastic change made to the specification does not affect them. The two can be merged later to make a comprehensive API reference.
4. Tag your Operations
Another great practice is tagging your operations with groups and status and creating multiple versions of the same spec, for instance: Dev, Public, Partner, and Internal for different stakeholders. With this, a team can work on the same spec without creating multiple versions, and expose only the portions of that spec to the people they want it to be exposed. While exposing an Internal API, out of many hundreds of endpoints, choose the ones you want to make public while keeping the original spec as a single source of truth.
5. Merge your API Specifications
As your API team expands, you have multiple teams working on different services, the recommended practice is that specs for those services are maintained independently. Developers working on those services, as soon as they are done the building, update the spec and get it out. However, maintaining these services and specs separately does not mean they have to be exposed to the user in a similar fashion. Merging these different specs into a single unified one can provide the advantage of presenting a single view, single documentation, single library, and a single mock service.
Few specification formats, especially the OpenAPI format is flexible enough to achieve this and anybody get a pipeline running by just writing a script. But the tool that we are working on at APIMatic will be able to merge any specification into a single one regardless of the format and the nature of it.
6. Generate Changelogs
This is another form of validation that you can achieve before making your specification public. Let’s say a developer comes in and makes an optional parameter, required. Now that would make things different for the user, and would not want this released without a version bump or release notes.
Swaggerdiff is a tool that can help you avoid that. Although it can work with just OpenAPI formats, for now, you can always make use of API Transformer to convert your spec to the format it supports and then run rests for your specifications to detect breaking and minor changes, which can be rendered in form of change-logs. A little work by your documentation team and they’d be good to go for your audiences as well.
What’s Next?
Now that you know what practices you need to follow to make sure the Spec is produced in a neat, clean and well-organized manner, it’s now time to consider the big question. What can you do with that spec, or why do you need such a well-rounded spec in the first place? Stay tuned for the next blog in line, which will discuss what can be done with a great-looking API specification.
