Despite being the lingua franca of the internet, APIs remain wildly inconsistent in both their structure and documentation for developers. While the promise of APIs has largely been fulfilled, their actual usage for developers day-to-day often remains frustrating. Since an API in and of itself is just the mechanism for a service to offer access (both internally and externally), there are no specific rules around its implementation.
In order to provide some much-needed consistency, multiple options for API guidelines have been created. So just what is an API specification?
Nordic APIs has a great article describing in detail the differences between an API specification, documentation, and definition. Check out their article for a much more in-depth discussion, but basically a specification describes the overall behavior of the API and how it links to other APIs. Documentation for the API provides examples, a detailed reference, and the specific API functions. Finally, while the specification and documentation are geared toward humans, the API definition is more for machine-readability.
So what does this mean for developers? While it’s easy to get down into the weeds, at a high level I think it’s important to at least understand specifications and the options available. An analogy I’ve seen for API specifications are house blueprints. You wouldn’t start building a home without a blueprint and an API is essentially the same logic. Understand and document in advance what you’re building so everyone involved remains on the same page before, during, and after creating the API.
Some of the advantages of using an API specification include:
– can be machine readable, providing the ability for automated code generation
– built-in documentation – you’re writing the docs as you go
– uniformity
– catch problems early on in development
– easier to test
And some disadvantages include:
– the specs can be overly verbose and complicated
– depending on developer preferences, they can actually be less readable
– each spec has industry backing which influences the overall direction
There are three main API specifications: Swagger (OpenAPI), RAML, and API Blueprint and each has an industry sponsor (SmartBear, MuleSoft, and Apiary respectively). All three are open source, offer code generation tools, and have active developer ecosystems. The following is a quick look at some of their differences.
Swagger
– largest community and developer ecosystem
– supported by large corporations like Google, Microsoft, and IBM via the Open API Initiative
– the format is JSON
– easy to use tools to generate nice looking online documentation
– a possible negative is developer focus, meaning they’ll be the only ones creating the documentation (as opposed to other stakeholders)
RAML
– the format is YAML
– very succinct/concise
– balances human readable with machine readable
– good for quick prototyping, but may break down with large documentation as nested YAML
API Blueprint
– the format is Markdown, so very human readable
– focused on “collaboration between project stakeholders, developers, and customers at any point in the API lifecycle”
– built for a “design-first philosophy”
All three provide tools and support for building out robust APIs. In order to choose between them, I’d look at a couple factors when you’re considering a selection. First, do you like the language they use? What do you feel most comfortable working in? If you can’t stand writing YAML, then you’d probably want to avoid RAML. That recommendation sounds like common sense, but these types of personal preferences really matter long term. Second, try to think again as to what you’ll need to do with the API you create. Will you have a requirement to automatically generate SDK code from the specification? Does your API documentation need a nice looking UI to publish on the web? Taking account of these considerations from the beginning can help point you in the right direction for a specification choice.
I’ll leave it out of this discussion, but there are also numerous API frameworks and platforms that provide infrastructure benefits for your API. I’ve never used any of them personally yet, but here’s a list of the more popular ones to jump start your research: IBM API Connect, Apiary, Apigee (now Google), Mulesoft, and Mashery.
In the next two articles of this series, I’ll discuss Swagger in more detail as my preference of the three main specifications, how to use it as an initial part of building your API, and how to create a Ruby SDK automatically from a Swagger specification.
