The Current API Definition Landscape
Defining the surface area of your APIs in a machine readable way is nothing new--we’ve had Web Services Description Language (WSDL) since early 2001. While WSDL is still a very viable way to define your web services, there has been many advancements in the ways you can define web APIs in 2015.
I have included WSDL in here for the sake of storytelling and discussion. However, in my research, I am focusing on API definition formats that can be applied to web APIs. Web Application Description Language (WADL) was the first format that gave us a way to describe the metadata around an API, but it wasn’t until Swagger emerged, that API definitions were even a segment of APIs--resulting in several competing formats to choose from in 2015.
So what does an API definition do? It provides a machine-readable format for you to describe the surface area of an API. They o en start with the name, description, tags, and usually a base URL that can be used to find the APIs. The formats quickly go further, allowing you to describe each endpoint, including its verbs, parameters, and other detail you need to make an API call. While each format has their own approach, they also provide you with a way to describe the responses returned from each API, which potentially as much detail about the underlying data model as possible.
About the Author
My name is Kin Lane and I am a technology professional with an obsession for Application Programming Interfaces, also know as APIs. You will find me half the year, traveling the world evangelizing the importance of API literacy, and the other half of the time, working virtually to better understand the world of APIs, and publish my ongoing research, and stories on my network http://apievangelist.com.Follow on Twitter More Content by Kin Lane