API Blueprint Evolving Where OpenAPI Spec Falls Short

Z (@zdne) over at Apiary published a pretty interesting blog post before Christmas which highlights two important elements of profiling APIs using popular API definition formats. Z is key to the vision behind API Blueprint, one of the top 3 API definition formats, that are fueling API design in 2016. 

Giving the Body Some Love

One common complaint I've seen on forums, issue threads, and other places API developers hang out, is that OpenAPI Spec does not allow for properly describing the request body payload. I definitely agree with this but is something that doesn't often impact me, as the type of APIs I am currently deploying, rarely employ a very complex body payload. However, I do know some APIs that I've documented, where if you can't properly define the body, the API appears to have no value whatsoever, when described using an OpenAPI Spec.

It was good to hear Z state:

"In 2015, we have spent most of the year building only one feature--the description of body parameters. This feature is also know as the MSON syntax." - Z (@zdne)

Acknowledging Media Types

The next significant area Apiary is addressing with API Blueprint and MSON is when it comes to supporting multiple media types, and making sure they are properly described in the API definition--MSON, 

Z talks about how "MSON isn't another syntax for JSON. MSON is agnostic to serialization media types. With MSON, I can describe the data and defer the decision whether they will be sent as JSON, XML, or HAL over the wire."

I will be learning more MSON in January, and reacquainting myself with API Blueprint, as I document my APIs stack(s), but also specifically two of my APIs that provide JSON, HTML, and Siren media types. Hopefully, this will allow me to also document the growing number of hypermedia APIs available across the space.

Media types and body are two areas that OpenAPI Spec (aka Swagger) is deficient. Something that gives Apiary a pretty interesting head start when it comes to two pretty fundamental building blocks of the web, and, therefore, APIs. I was going to start using vendor extensions, to begin playing around with content-type negotiation in my OpenAPI Spec files, but I might just invest my energy into sharpening my API Blueprint skills, and definition repository instead.