This talk was presented at API The Docs Virtual 2020 event series on 27 May. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit our talk recaps ToC page for an overview of all presentations!
“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:
Addresses all types of audience:
What are the benefits of OpenAPI Spec (OAS) compared to other API Documentation Solutions (API blueprint, Javadoc, Doxygen, RAML, WADL)?
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.”
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.
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
HTTP Status Codes (Successful Responses, Client Errors, Server Errors)
Use of headers
Use of method types
Consensus on using REST Best Practices
Establish parameter naming conventions
Find learning resources and tools of how to get started with OpenAPI Spec on the last slide.