One of the most common types of development work done at Atlantic BT is building APIs. An API (Application Programming Interface) is a set of defined rules that allow different software applications to communicate and share data with each other. The APIs we develop at Atlantic BT are used not only by the websites we create, but by external clients and third-party services. Therefore, defining, documenting, and testing these APIs is a critical part of our process. This blog post will showcase several helpful tools that we use while building APIs for our clients.
Defining and Documenting APIs
Defining and documenting your API is an important step when building and maintaining an API. Regardless of whether the consumer of your API is an internal or external user, having a clear understanding of how to interact with your API is essential for making the development process as smooth as possible. Fortunately, there exists a suite of tools to help with this.
Swagger
Swagger (referred interchangeably with Open API) is a standard, programming language independent way to describe APIs. When defining your API, you create an Open API specification that describes your API’s endpoints, input/output parameters, and authentication methods. This specification can then be used to generate interactive documentation and client SDKs.
Swashbuckle
https://github.com/domaindrivendev/Swashbuckle.AspNetCore
Swashbuckle is a .NET library that automatically generates Open API standard documentation from your existing API code and provides a user-friendly UI for testing them. This is great for legacy applications that may be missing documentation. With minimal code, Swagger documentation can be generated, giving developers and API users specifications that would otherwise take considerable time to write and maintain. While Swashbuckle is a .NET specific library, there exists comparable tools made in almost every language.
SwaggerHub
SwaggerHub is a collaborative platform designed for API development that leverages the Swagger/OpenAPI standard. It provides a centralized place to manage and version your API documentation. At Atlantic BT, we use SwaggerHub when building APIs that need to be consumed by our clients. This allows everyone involved to always have the latest API definition, which makes collaboration with our clients much more efficient.
Testing APIs
Once your API has been defined, and development has started, testing that API becomes the focus to ensure it is functioning as expected. Once again, there exists a variety of tools to help with this important step.
Postman
Postman is an API testing tool that offers a user-friendly interface for making requests and viewing responses. It allows you to save and organize your requests in collections, which helps if you work on multiple APIs or work with many clients, as we do at Atlantic BT. It allows simple control over the headers and body of the request, which make it our preferred tool when we quickly need to test out an API endpoint.
Webhook.site
One of the common scenarios that leads us to develop an API for our clients is to receive data from a webhook on a third-party site. A webhook is a method used to send notifications to other systems by making an HTTP request to a specified URL whenever a particular event occurs. When developing this webhook API endpoint, the problem is that the computer you use to do development work on often isn’t publicly accessible by the site sending the API request. So how are you supposed to know what the webhook data looks like? One way to solve this problem is using Webhook.site
Webhook.site gives you a unique publicly available URL that you can have a site send requests to. In addition, it has a simple interface that allows you to view all the requests that are sent to that unique URL. You can then copy the request data that was sent and paste it into Postman running on your computer to send to your in development API.
ngrok
Another solution to testing a webhook is to use ngrok. ngrok is a tool that runs on your computer and creates a secure tunnel from a public URL to your local machine. This allows you to expose and test your local API over the internet. Using ngrok will let you test the full flow of the webhook without having to use the extra steps of having data sent to Webhook.site and then sending the data again using Postman. ngrok also allows you to inspect and replay requests, which is helpful so you don’t have to trigger the webhook repeatedly.
Conclusion
Whether an API is public-facing or behind the scenes, it is an integral part of modern web development. Regardless of the purpose of the API, documenting and testing are key steps in our software development process at Atlantic BT. And with the help of the above-mentioned tools, it allows us to be more detailed, rigorous, and consistent when building and maintaining APIs for our clients.
