Joan James - How the Open API Specification led to Better REST API Design

“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
• Use cases
• Descriptions and examples of every call and parameters

Addresses all types of audience:

• Developers - internal, external, newcomers, debuggers
• System architects
• Designers
• Decision makers

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.
• Stable implementation.
• Numerous tools available based on the Spec (editors, plugins, code and test generators, documentation rendering engines, mocking tools, conversion tools).

API-first design

• 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

1. 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.

2. 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.

3. 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

• Living document

• Change control process

• Industry best practices are followed

Parameter naming:

• Query Parameters
  • Appended to the URL
  • Single lowercase word or Camel Case compound word
  • No one ever should type it manually
  • Filters
     
• Path Parameters
  • Part of the URL
  • Single lowercase word or Camel Case compound word
  • Contains the key for the database
  • Only for documentation
     
• Header Parameters
  • 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)

• Versioning

• Use of headers

• Use of method types

• Resources naming

  • Data driven approach
  • Function driven approach

• Authentication

• Consensus on using REST Best Practices

Lessons Learned

• Establish the API naming early
  • API name
  • Resources URL naming

• Establish parameter naming conventions

• API-first!

Find learning resources and tools of how to get started with OpenAPI Spec on the last slide.