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?
Yes.
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 (https://raml.org/), API Blueprint (https://apiblueprint.org/) and OpenAPI (https://github.com/OAI/OpenAPI-Specification). 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!
offbeattesting 
Thaanks for this blog post
LikeLiked by 1 person