When you do a web search for “how to build an API”, I found that quite a few options come up, but very few are end-to-end guides. This may be due to my poor web search abilities or because it’s quite hard to build an API (getting it from design to production).
Anyone that works with APIs will tell you that it can be quite the feat, and a team of people usually manages it. So building an API yourself and getting it into production so your users can start using it can be a significant challenge.
We live in a fortunate time where there are many tools that make this task much more manageable. With something like Postman, we can create the API specification, test the API specification and ultimately test our API to ensure that it is working as expected. To build the back end of our API, we will need a host of tools such as Flask, Heroku and more, or we can opt for a low-code tool to build and host our API.
In this post, we will look at the process of building an API and how this process can be made more efficient.
API Development process
API development is complex, there is no way around it. Typically we need to design the API, code, test, debug, code again, test some more, deploy when we are ready, and then there is the seemingly endless maintenance. A typical API development life cycle will look something like this:
Each step in the process will typically be done by another tool or resource, so it can become quite an endeavor to implement an API.
For example, we might opt to use Postman to design our API (Open API Specification) and use something like flask for our code connect firebase or some database to store or retrieve our data. We might also need to make additional REST calls to other APIs and services. To test, we can use Postman again, but debugging the code and all our connectors can become troublesome. For deployment, we might opt for Heroku, but it depends on what our API requires. For monitoring, we can either create our monitoring system or use something like Splunk. And when we need to maintain our API, we need to dive back into all of that. You get what I am trying to say. API development is complicated.
Finding a better way
I wanted a way to simplify the API development lifecycle and to develop my APIs from design to production with only a hand full of tools. Thanks to low-code tools like Linx, this is possible. I was able to create an API, from design to deployment, using only three tools:
- Postman I used postman for creating my API specification (YAML based) and for testing my API
- Linx I used
Linx to build my API, implement the logic, debug it and finally to host it. Quick note, you can also try your hand at building an API with this guided tutorial. - SQL Server SQL Server was used to store data for my API. I used the pre-created AdventureWorks2019 database and its data.
The requirement
I opted for a straightforward API that will do user record maintenance. The API has five methods:
Creating the specification
I created a straightforward API specification in Postman using YAML that matches the requirement. Postman allowed me to see what I created and visually provided additional information. Creating the API definition in Postman also benefits it already sets up that API for testing. If you choose to, you can set up the testing scripts at this stage.
Building the API
Now that I have the API definition, the code can be created. Linx allows you to import an OpenAPI 3.0 specification and will automatically generate the events for each method specified. I only needed to specify the URI and then build the logic.
Creating each event’s logic goes relatively quickly once the database plugin is installed. Linx does have a learning curve like every tool, but once you understand how to work with it, the pace picks up.
I added logic and functionality to each event for the API. For example, for the GetAllUsers method, we all needed to read from the SQL database and return the results via the response body.
Testing the API
Because the API is already set up on Postman, it was quite easy to test, in real-time, how the API operates now that the logic has been implemented. The GIF below shows how I used the Linx designer to debug the REST API I have created and how I am testing it in debug mode.
GIF
With the API being debugged in Linx, it’s being hosted so that I can call it to see how it will behave when I deploy. This allows me to test and get an actual result back:
Of course, we can also add test scripts in Postman to automate our testing process. These scripts will ensure that you are getting the correct response.
Deploying the API
Now that the API has been designed, developed and tested, it needs to be deployed. This can be a substantial task with traditional API development as we need to come up with a deployment strategy, figure out where we will be hosting what and make sure that monitoring and logging are taken care of and more.
My deployment was quite simple. I deployed the API from the Linx Designer directly onto the Linx Server. It took about 2 minutes for the solution to be built, pushed to the server, and ready for use. The difficulty of hosting an API is removed as the Linx server handles this. It also does monitoring and logging:
I called the GetUser method with an incorrect ID to see what would happen if an unexpected error occurred. The server logs the error and indicates with red that an error occurred:
I was able to call the API from Postman again, and the server gives an indication each time that the API is called.
Admittedly, I did not add any form of security or authentication to my API, but these settings are available in the Linx designer. Another option I tried was to generate the API Documentation in swagger format. This turned out to be quite valuable because by adding /swagger to the base URI, the documentation is available and hoasted with the API itself. This makes it easy to distribute API documentation when needed.
Wrapping up
When combining Linx and Postman, we can design, create, document and host APIs. It does take a bit of getting used to, much like any tool. Because Linx uses standard programming paradigms and jargon, it is easy to pick up if you are familiar with a programming language like C#. I do feel that we save the most time when deploying and hosting an API with Linx. Monitoring and hosting are done for you, meaning that a substantial headache is taken care of. If the logging and monitoring are not granular enough, you can add your functionality to the Linx solution.
If you want to try building an API with Linx, you can try it yourself
- using
design first (with Postman) or code first (just build)
Also published here.
