Developing API clients doesn’t have to be a pain

Photo by Federico Beccari on Unsplash

I work with APIs all the time, and over the past years, I’ve had my fair share of building API clients. In this article, I want to focus on tips that make it easier to build API clients.

What’s an API client? An API client is any piece of code that consumes an API. Typically, that’s a frontend application, but it can also be a backend service, a command line application (CLI), or a piece of automation code. See this article for more information.

APIs are fundamental to microservices architectures, since it’s through APIs that services can talk to each other. There are many different types of APIs, but here I want to focus on web APIs. In particular, the likes of REST and GraphQL.

What are the biggest mistakes I often encounter when working on API clients?

1. Not having an API specification ready from day one. I’m a big advocate of documentation-driven development for web APIs. An API specification is a contract between a server and a client. The specification states in an unambiguous language what the client is expected to send to the server, and what the server is expected to send to the client. If you implement both the server and the client against a specification, you can be fairly certain that both will integrate without almost any errors. Without a specification, God help you.
2. Writing the specification in a non-standard format. I’ve come across several situations in which people stubbornly resist using standards in API specifications. Instead, they use unstructured text to “document” the API in platforms such as Google Docs, Confluence, SharePoint, etc. What’s the problem with this approach? The problem is that you’re giving up the entire ecosystems built around standards to help you build, test, and maintain your APIs more easily. When you use standard specification formats, like OpenAPI, you generate automatic tests against the API, get nice API visualisations like Swagger UI, or run a mock server. When you go your own way, none of this is available to you.
3. Waiting for the server to be implemented. I often hear that you can’t start working on the client until the server is ready. This is utterly wrong. If you have the API specification ready from the start, then you don’t need to wait for the server. Waiting for the server to be implemented only delays the development process, and you may end up with arbitrary API designs that seldom consider the needs of the client. Also, bear in mind that backend developers, like all developers, can create bugs or make mistakes. Without a proper API specification to validate the server implementation against, you’re walking in the dark.
4. Testing the client against the server. When you’re working on your API client, be it a frontend application or a microservice, you sure want to be able to test it against an actual API server. This often involves setting up and running a local server. That’s not always optimal or even desired. Why? Because setting up and running the local server may not be straight forward. The API may be implemented with a technology you’re not familiar with, and it may have dependencies that aren’t easy to install. Trust me, even if you’re running everything with Docker, you’ll encounter setup issues sooner or later. The API server may also have bugs that make your testing unfeasible, or at least unreliable.

In some cases, I’ve seen developers resorting to just using mock data or fixtures to develop and test the API client while the server is being readied. This works to an extent, but it’s yet another sub-optimal solution, because you need to maintain those fixtures, and you need to make sure they look exactly like the payloads that will be returned by the server.

The better alternative is to test against an API mock server. To run a mock server, you’ll need an API specification written in a standard format (e.g. OpenAPI for REST or Schema Definition Language for GraphQL). What is an API mock server? It’s a server that runs your API, but instead of returning real data, it returns fake data which is compliant with your API schemas. It looks and feels like the real API server.

To address the problems described above, these are my recommend the following strategies:

1. Start with an API design and specification from day one. Work on the specification before you even start working on the API server. Once the specification is ready, both teams working on either side of the API will be able to work simultaneously and independently against the specification.
2. Make sure you write the specification in a standard format. If you do, you’ll be able to leverage the whole ecosystem of tools built around APIs. For example, you’ll be able to use Dredd to generate automated tests for the API server, and you’ll be able to use Swagger UI to visualise and interact with the API.
3. Use an API mock server to build and test your API client. There are various tools and frameworks for this. Here I’ll describe you two different tools you can use to run an API mock server: microapis.io and Stoplight’s Prism CLI.

Microapis.io

If your API specification is written in OpenAPI v3+, you can use microapis.io. I built microapis.io to make it easier to run API mock servers for quick integration tests. With microapis.io, you can get a mock server up and running with the click of a button. No signup or login required. To use microapis.io, take the following steps:

1. Paste your API specification into the input text area.
2. After pasting the specification, make sure you click outside the input area so that the input is registered. MicroAPIs will first validate the specification. If the specification isn’t valid, you’ll need to fix it first. You can use something like Swagger’s editing tool to fix your API specification.
3. Click the “Mock this API” button. After you do that, you’ll get two URLs:

• A base URL where your API mock server is available. This URL is valid for an hour. If you need the mock server longer than that, you can simply click the button again to get a new URL.
• A sample URL of your mock API mock server. This URL is offered for illustration purposes, to give you an example of how you build your API requests using the base URL. You can directly click on the sample URL to inspect the sample response.

The GIF below shows how to get the server running:

Generating an API mock server with microapis.io

I’m actively working on improving microapis.io, so for any feedback about its usability or any request features you’d like to make, please feel free to reach out to me!

Prism

If you’d rather run your mock server locally, I recommend Stoplight’s Prism CLI. Prism is a npm package, so you’ll need a node.js runtime available locally. You can install Prism via yarn or npm. To install Prism with npm, run the following command:

$ npm install @stoplight/prism-cli

To run your API mock server locally, you simply need to pass your API specification to the prism command, like this:

$ ./node_modules/.bin/prism mock api-specification.yaml

After this, your local API mock server will be up and running and ready to use!

If you’re interested in learning more about building APIs and microservices, check out my book Developing Microservice APIs with Python, published by Manning. The book is still in development, and you can access it through the Manning Early Access Program (MEAP). This means that you get the opportunity to suggest changes or improvements to the book, and I’ll be able to incorporate them. If you’re interested in the book, you can use the code slperalta to get a 40% discount. You can also download two chapters for free from the following URL: https://www.microapis.io/resources/microservice-apis-in-python.

I’d really love to hear your feedback about the book!

Cover of Developing Microservice APIs with Python