Having spent the better part of the last year working on one project that is completely reliant on a third-party API. As well as another project, that is heavily reliant on several third-party APIs, I have developed some opinions on the matter that, in my own journey to improve as a developer has inspired some of my own behaviour.

Challenges

In particular, one of the mentioned third-party APIs has been somewhat difficult to work with due to the fact that:

1. There is no Swagger UI (or equivalent) to interact with. As such, I needed to construct my own PostMan collection to make testing/exploration easier.
2. The documentation, while decent, is separate from the tool I use to test, as such, I need to continually switch between a developer portal and PostMan. (If you account for the 15 minute time out on the developer portal, it can get painful having to switch and login continually)

As a result of the above, after some searching, I came across Swagger and the concept of API-First design and development. As I see them, the benefits of designing (and sharing) the Swagger document up front are as follows:

Benefits

• API's can be designed and distributed (thus starting the feedback loop earlier) before any code is written.
• Tests can start to be written sooner.
• Mocks can be setup sooner, which enables the front-end team to work without having to wait on the back-end team.
• Deliverables can then be validated against the specification to make sure all is as it should be.

With these in mind, and with the goal of improving my own development skills and habits, I set about with the following goals when starting to build my example Itemly todo API:

Goals

• I first wrote, and included a swagger.yml API specification document in the repo.
• I have included Swagger UI from the beginning (using @nestjs/swagger). Despite the app being rudimentary, it is important to enable a mechanism whereby anyone can start to interact with, and manually test the APIs while in development.
• I have included Typedoc early on for code documentation.
• In future, I will add an API collection document (i.e. PostMan or Insomnia) to the repo so that, if needed, these collections can be shared or used in API testing should someone not have access to Swagger UI for some reason.

Process

1. I write my .yml in VS code (in order to better learn the structure)

2. While writing, I run the file through the swagger-cli in order to validate as I go.

   npm i -g swagger-cli
   swagger-cli validate swagger.yml
   

3. Once ready, or when completing endpoints, I will paste the spec into the online Swagger Editor for validation (the validation and error messages are pretty good here)

Improvements

Looking at the API writing process above, admittedly, it is not particularly efficient. Some areas for improvement are:

• I could include swagger-cli into an npm task - swagger-cli validate error messages, while useful, do not include line numbers - hence the pasting into the Swagger Editor.
• On that note, the Swagger Editor has the great benefit of being able to instantly generate the Swagger UI on the fly, which really helps one "see" the API a lot better.
• I will look for a VS Code extension which can validate the Swagger document within VS Code itself.

Research

Another area I am currently looking into is how to effectively mock the API - either by using a tool such as WireMock or Mock Server, or by finding a tool to which I can pass the Swagger document and it will generate the mocks for me - something like Swagger Hub, PostMan or Stoplight might be candidates in this area. However, I will share more on this in a future post!