“The OpenAPI Spec is a contract. I also think of this like an orchestra score. Everybody thinks that with the concept of agile and MVP there are a lot of developers who want code-first. But what if an orchestra just showed up and the musicians all just sat down and played whatever they wanted? Well, that’s not gonna work. A contract is an agreement between multiple parties that they are going to march to the same drummer.”
Why do you have API Documentation?
To instruct the audience. It provides:
Overview of the API
Descriptions and examples of every call and parameters
What are the benefits of OpenAPI Spec (OAS) compared to other API Documentation Solutions (API blueprint, Javadoc, Doxygen, RAML, WADL)?
Depending on how the OAS is generated, it can be the single source of truth for the API structure.
You can review the developer provided descriptions and attempt to change them, for example in the code if your tools to generate the Spec are applicable.
API-first design enabler.
Numerous tools available based on the Spec (editors, plugins, code and test generators, documentation rendering engines, mocking tools, conversion tools).
Have an agreement with the developer partner.
Design the interface (inputs, outputs, paths, methods, data models).
Enable mocking for testing the behavior.
Design consistent APIs.
Why do we want API-first design?
Having the OpenAPI Spec before any code is developed, some kind of governance can be provided on the Spec. But how could this be done?
“At Zebra, I’m part of an API management team, which is comprised of a product manager, a program manager, a developer portal owner, and the engineers that developed the proxies on the Apigee platform. We all learnt about the OAS together. The team is very supportive of my role which has helped me gain the trust of the API developers.”
API management process at Zebra Technologies
The entrance criteria for the API management process is the OpenAPI Spec. Review the OAS with a customized linter. Develop a naming requirement for API Products and basepath URLs. The more APIs you have the more you realize you should have had a naming master plan.
Developers work in parallel and test the code and the OAS between phases based on their test criterias. Once you render the Spec on the developer portal, there is a button to try it out. Testing of the documentation is the care-taking of the try-out functionality.
Final reviews of all the documentation and the developers’ final testing by following a checklist before public release.
What if there are problems within the OAS?
Have an agreement and teach yourself on REST API best practices to solve the occurring issues.
What kind of problems can there be?
URL structure: what if your APIs are very similar to someone else’s APIs but their URL structure is completely different?
Versioning: there are all kinds of ways for versioning (e.g., version on the path or on query parameter), what if another part of the company does it differently?
Resource naming: the part of the path that comes after the fully qualified domain name, you have to have a master plan and know the basic rules: e.g., shouldn’t put a verb in it.
Parameter naming: be consistent, have conventions to make it easy-to-guess.
Header usage: have an agreement.
Error Response inconsistency: should be documented and used in the same way, use the standard ones.
Authentication: have an agreement on what type of scenarios you’ll use.
“A design handbook for REST APIs that were created when we started on the journey of cloud APIs. It was a very good tutorial but it lacked the necessary agreements, like: how do you name parameters.”
An Architecture Task Group was able to address all the issues in a problem statement and the consensus was documented.
Goals of the Architecture Task Group
Easily accessible guidelines for API Design
Viewable by all Zebras
Uses language understood by API designers and business analysts
All Business Units represented: subject matter experts of their own fields
Change control process
Industry best practices are followed
Appended to the URL
Single lowercase word or Camel Case compound word
No one ever should type it manually
Part of the URL
Single lowercase word or Camel Case compound word
Contains the key for the database
Only for documentation
Custom headers that are expected as part of the request
Body (or Form)
Appended to the HTTP request
The name of the parameter is used for documentation purposes only
Aspects that need agreement
HTTP Status Codes (Successful Responses, Client Errors, Server Errors)
Use of headers
Use of method types
Data driven approach
Function driven approach
Consensus on using REST Best Practices
Establish the API naming early
Resources URL naming
Establish parameter naming conventions
Find learning resources and tools of how to get started with OpenAPI Spec on the last slide.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.