Some say machine-readable specifications are “contracts”. To me that sounds like bullshit marketing. Spec files describe the API features. Neither the consumer nor the provider is signing anything. I see the contract babbling just as an attempt to bring legal semantics to tech talk to raise credibility. Credibility of the API is measured with reliability, efficiency and ease of use. Those have nothing to do with spec files. Specification files should be seen as part of the documentation - that’s it.
Major part of great developer experience for APIs is up-to-date documentation. In Platform of Trust that is generated automatically as part of CI/CD process. The overall process as picture below. Most of the APIs nowadays provide nice documentation as more or less generated webpages. Optimum result is found with combination of automation/generation and manual work. That applies to us as well. At the moment code examples provided to each API endpoint and manually crafted. We are testing if automated code generation could bring some value in the process, but for now we do those manually.
Despite the minor manual touch, 95% of the API documentation is generated from machine-readable API specifications as part of automated CI/CD process. In other words, we are using the spec files to avoid manual work and to ensure that documentation is always up-to-date. No alt text provided for this image
Response to customer needs
During the spring 2019 first customers (developers) of Platform of Trust have asked us about the availability of API specs. By this request they often refer to OpenAPI specification or alike. The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
With help of the spec files, developer can for example:
- View the documentation in Swagger UI. You can use URL to provide content just like here https://editor.swagger.io/?url=https://docs.oftrust.net/specs/oas/identity-api.json
- Generate clients with ready-made tools such as codegen
- Replicate API in closed internal development environment for development purposes.
- Import the file to API testing clients such as Postman and Insomnia.
Our internal format for describing the exposed APIs is RAML for reasons of better fit into our own development practices and tools. In brief internal developer experience defined the format, not popularity of the spec format. Luckily as part of the API documentation generation, we do convert RAML files to OpenAPI spec files before generating Slate framework content. Thus providing downloadable API spec files was not a big deal for us.
Low hanging fruit for us
The feature to provide OpenAPI spec and RAML formatted spec files as part of the API documentation was implemented in couple of hours. Initially the idea was to add links to API description in the mid column in the documentation. After some thinking, a better place was found. Those should be provided in the right-most column in which code examples are. See docs.oftrust.net
Intention is to add link to Insomnia package for the API testing in the same “resources” package in API documentation. Of course the API consumers can import the API spec files one by one to API test client (Insomnia), but our idea is to provide one package which contains settings for environments (sandbox, production) as well as all the APIs. This saves API consumers time dramatically.
Why Insomnia and not Postman? Internal Developer eXperience dictated the choice. Insomnia was the preferred tool for the internal developers. I’ll discuss the API clients in the following post.
Some more to read from 100 Days DX
- #85 - Great Developer eXperience requires fluent internal workflow
- #84 - Theory of Economics of Developer eXperience
- #83 - The Space of API Design Decisions is missing
- #82 - Purpose of API Evaluation Framework
- #81 - Should We Move to Stack Overflow?
- #80 - Four data driven ideas for improving API documentation
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!