Getting Started with API Specification Languages

Getting Started with API Specification Languages

The quest for ever higher levels of abstraction never ends in computing. I used to work at a company that still ran some FORTRAN code. Although out of date now, the invention of FORTRAN in the 1950 was revolutionary in the way it abstracted away the need for humans to work with assembly language and punch cards. Fast forward a couple of decades and object oriented languages like C++ came along with increased levels of abstraction. Then we got rid of the need for humans to do garbage collection and memory allocation in increasingly abstract languages. We have continued to created additional layers of abstraction through widespread use of libraries and I would argue even through the increase use of APIs.

But we didn’t stop there.

Once APIs become widespread, we started looking for ways to simplify our interactions with them. This is where API Specification languages come into play. I want to explore some of the different specification languages that are in common use over a few blog posts. Before diving into specific specifications though, I want to look at what an API specification is.

What are API Specifications?

API specifications provide a structured way to define an API. If you follow the rules of the specification, you can interact with the API at a higher level of abstraction. For example, an API specification could be used to automatically create mock servers that you can use for testing and experimentation during development. You can also do things like automatically generate documentation and contract tests. You can even use these specifications to generate some kinds of code, for both server implementations and for client side code that calls the API.

RESTful APIs follow an architectural style laid out by Roy Fielding in his doctoral dissertation. This means that there are general principles laid out that they follow, but there is not a strict protocol that they must adhere to. This balance between structure and flexibility has been a powerful concept and has contributed to the widespread adoption of this kind of API architecture. There is no such thing as a perfect solution, however, and this one is no different. For example, one of the benefits of strict API protocols like SOAP is that the structure must be specified following strict programmatic rules. This means that the API definition must be written in a way that computers can easily understand. This makes it easy to create a lot of general-purpose automation for these kinds of APIs. If a computer can understand the layout of an API, you can automatically generate some kinds of documentation, tests and even code from that specification.

Without that strict specification, each RESTful API may have some nuances to it that are different from others. As humans, this is generally fine. We can quickly and easily figure out where those differences are and accommodate them. Computers struggle with this. Things have to be very clearly and explicitly laid out for a computer to use it. This challenge with RESTful APIs was recognized pretty early on, and so some API specification formats were proposed.

Should you use an API Specification Language?


And no.

Asking if you should use an API specification language is like asking if you should use a hammer. In order to answer that question, you need to first know if you are trying to get in a nail or a screw. Whether or not to use it depends on what you are trying to do.

API specification languages are good for helping you solve certain kinds of problems. They can help to keep things consisent between documentation and the functionality of your code. They can also be used to help you design APIs and to establish and enforce contracts around how an API should work.

However, there are downsides as well. If you want to use an API specification you need to be willing to maintain it. They often won’t have much value if you let them get out of sync with the underlying code. There are tools that can help with this maintance, but it is an important consideration if you are looking to implement the use of an API specification. Since using API specifications can cause some additional overhead they are usually best suited to scenarios where you have multiple people across multiple teams working on a set of APIs and where you need clear and unambigous ways to communicate how an API works.

So should you use an API specification language? I would say that unless you are working on a very small API with a small team, it is something worth considering. In my experience many development teams could benefit from a little more rigour in their processes and API specification will help with that. Just go in with your eyes wide open and don’t expect it to be some kind of magic pill. As with anything, it take hard work and discipline to use well.

Types of API Specifications

There are three main RESTful API specifications: RAML (, API Blueprint ( and OpenAPI ( Previously OpenAPI was called Swagger, so if you hear anyone talking about Swagger, just realize that it is the same thing as OpenAPI.

Over the next couple of weeks, I will share posts diving into these three API specifications and how to use them, but for now I just want you to have an idea of what they are. API specifications can be a powerful testing tool. You can use them to keep documentation, tests and even underlying code all in sync with each other. They can also be a tool that helps to maintain contracts between different parts of an application and can help less technical people get included in the design and testing of APIs. As I go through how to use each of the specifications, I’ll talk about this stuff in more detail. Stay tuned for more posts in this series!

Photo by Tim Gouw on Unsplash

What Problems do your Customers have?

What Problems do your Customers have?

Back in the days before COVID, when we could go to museums en masse, the Louvre in Paris had a problem. They had moved the Mona Lisa to a new room. The problem was, the room was only accessible through a single door and the resulting bottleneck led to many who had bought tickets being turned away or having to wait in line for hours to see the painting.

It was a horrible customer experience for thousands of museum goers. How many of them do think complained? How many requested a refund?

How do you know if you have a good quality product? Well, one of the things you could measure for that is how often you get customer complaints. Surely if there are very few clients complaining, the quality is good right?

Well, those museum goers who had a horrible experience: about 2% complained and less than 1% asked for a refund. I think there are two lessons to learn here.

In the first place, one customer complaint might just mean 50 to 100 other customers have the same pain point and never bothered to complain. Take customer complaints seriously. In the second place, you can’t rely on customer complaints to let you know when you have quality problems.

You need to do testing before releasing, and you need to have other ways of discovering problems that have been released that don’t require relying on customer complaints. When testing ahead of a release, don’t just look for functional bugs. Look for where users might experience pain. What things are going to give the customer a negative experience with the product?

Also, don’t just throw a product out there and assume that you’ll hear about the problems. Invest in some monitoring. Figure how to find those pain points for your customers and improve them without waiting for a complaint. As a software industry we have spent many years teaching people to put up with annoyances and frustrations. We can do better.

Photo by Mika Baumeister on Unsplash