Description of your REST API: Swagger & RAML

About a year ago I did a post about WADL. I hope you didn’t build a billion dollars business model around that initiative because it hasn’t left the ground yet :(

WADL, or Web Application Description Language for the initiated, was aimed to be what WSDL is for SOAP Web Services but for REST.

You see, the thing with REST that is so vastly superior to SOAP is its simplicity. You do not need a longish incantation of the XML Gods to cast a REST API. You simply need to be able to craft simple XML (or JSON) documents following an HTTP REST semantics.

One of the main problem with REST is its lack of self-description. Once you go beyond the proverbial calculator (always a super good example breaking about all distributed computing patterns) and that you distribute your API around, you will start to have Word or PDF or HTML documents describing your API. This is fine in the age of artisanal API but once you want consumer to plug and play your API, you would want them to do an “Add API reference” in Visual Studio or their favorite IDE.

Entered WADL. Actually, exit WADL: it was submitted to W3C in 2009 (by Sun Microsystems, oh yeah) and the W3C refused to standardize it.

Let me tell you about two contenders then: Swagger & RAML.

I heard about Swagger on Channel9, so I guess you could say that parts of Microsoft are looking into it.

Swagger has a very good head start in tooling with a lot of support in many target languages / platforms. It also produces a simple yet compelling UI.

You can look at the full specifications here, but basically it’s a JSON document describing your API. As a side-effect, Swagger enables the description of JSON document and therefore act as a sort of JSON Schema.

RAML is relatively similar to Swagger. Its format is YAML which is arguably more human-readable than JSON.

RAML seems to be less popular than Swagger but has several advantages, mainly:

At this point it really isn’t clear if either one will end up triumphing or if both will crash and burn. It is interesting to see the interest into an API description language is increasing though so I am confident that within years we will have a standard.

UPDATE:  It would appear that API Blueprint also is a contender.

Leave a comment