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:

  • Simpler to use to define a non-existing API (API design)
  • Existing features to manage repetition in an API (quite frequent)

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.

3 thoughts on “Description of your REST API: Swagger & RAML

  1. Pingback: SOA vs Mobile APIs | Vincent-Philippe Lauzon's blog

  2. Pingback: SOA vs Mobile APIs | Vincent-Philippe Lauzon's blog

  3. Pingback: Securing REST API using Azure Active Directory | Vincent-Philippe Lauzon's blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s