RAML – RESTful API modeling language

Swagger seems to have more awareness and adoption but we have fully embraced RAML due to its "composability" features which eliminate much of the boilerplate and copy/paste/tweak required by Swagger. Making the API spec easier to author & maintain is well worth the downsides of not being able to tap into the Swagger ecosystem. If we really needed something from the Swagger ecosystem, I don't think it would be difficult to create a RAML->Swagger converter. There is already a converter that goes the other direction.

But whichever one you choose, this stuff is awesome. We author API specs and then codegen mock services, client side wrappers (Angular services or Backbone models/collections), server side DTOs and controllers, and pretty documentation. Having that all done from a single authoritative text file under source control has drastically reduced the friction between frontend and backend developers.

joslin01• 11 years ago

I like this. I was using API Blueprint and I found it just way too verbose for simple things. This looks like yaml and has a nice simple way about it that appears to be easily expandable to cover all those complicated edge cases.

I suspect this will be a standards war for years to come until we finally settle on one API planning spec.

swalsh• 11 years ago

Very cool, it feels like WSDL for REST

EDIT: spelling

sgolestane• 11 years ago

WSDL :-)

Xophmeister2• 11 years ago

True REST shouldn't require a WSDL-like interface. The semantics of the graph it describes should be enough. This model, however, has yet to be fully realised; largely because of the large upfront cost in R&D. At my work, we are trying to develop in this area, but it's slow going.

cwp• 11 years ago

Can you expand on that? I've got a mature API that's based around HATEOS, json-schema and HTTP content negotiation. It works really well, but client-side developers always need some time to get used to it, as they expect "REST" to mean "like Rails".

mikegirouard• 11 years ago

Quite true, but the benefit of something like this is the ability for humans and machines to parse in one spot.

This can be both a spec and documentation at once. Client libraries can be generated and services can be stubbed.

Personally, I'd love to see something in reverse: traverse an existing restful service and produce a RAML document.

andersriutta• 11 years ago

We're playing around with related ideas here [0]. It's understandably slow-going, because it's a hard problem to make a system 1) respond correctly to highly-specified custom queries, 2) easy to use and 3) scalable/performant.

[0] https://github.com/Mec-iS/mild-QL/issues/3

pavel_pt2• 11 years ago

The good parts of WSDL, I presume? ;-) I spent way too long staring at raw WSDL, I almost think certain profiles are actually OK. But SOAP on the whole is a world of pain.

aikah• 11 years ago

It's funny how trends in web development work. 5 years ago , SOAP sucked and if you were using it or praising it you'd get laughed at because XML. Now REST sucks because GraphQL so let's go back to RPC like protocols and but with a twist , YAML or JSON ...

CookWithMe• 11 years ago

I wrote some RAML recently and found it very good for creating a machine-readable representation of an API. We also wanted to make it human-readable and use it as our API reference (with the API console). I found it to be mostly good, but had some trouble when explaining larger concepts that span several requests. Also, it's harder to point to the "important" parts of the API if it's sufficiently large than it was with our "freeform" reference.

I haven't looked into Swagger deeply, but RAML seems better at re-usability. Swagger seems to have way more traction though, and also more tools.

pavel_pt2• 11 years ago

Ditto, used RAML on a previous project and everyone involved really enjoyed it. It manages to capture just enough about how thinks work without getting overbearing. I particularly like the fact that it allows for examples to be specified.

I haven't built anything with Swagger but I never clicked with it the way I instantly did with RAML. It's a pity - there seems to be a lot more industry and open source support behind Swagger than there is for RAML which is mostly backed by MuleSoft.

earth2marsh2• 11 years ago

Swagger added support for examples with version 2.0 of the format, see: https://github.com/swagger-api/swagger-spec/blob/master/vers...

earth2marsh2• 11 years ago

If you're interested in re-use in Swagger, see the guidelines here: https://github.com/swagger-api/swagger-spec/blob/master/guid...

pksunkara2• 11 years ago

Can I suggest API Blueprint [1]? It is much more human friendly and easier to work on API design. Apiary has tools for complete API lifecycle management.

Disclaimer: I work on making API Blueprint better.

[1] https://apiblueprint.org

roguelynn2• 11 years ago

I wrote a Python parser for this called RAMLfications (https://ramlfications.readthedocs.org/en/latest/)

I actually built the API console for my company - Spotify (https://developer.spotify.com/web-api/console/) - based off of RAML and am in the process of open sourcing the tech behind it. The first bit being RAMLfications, and the second, called Griffin (https://github.com/spotify/griffin) is a super alpha version of a static doc generator based off of RAML. The next/last bit to open source is the console itself, as well as some integrations like Flask extensions/Django packages.

gary4gar• 11 years ago

What are you using for ref docs? https://developer.spotify.com/web-api/get-album/

roguelynn2• 11 years ago

Currently this is just Wordpress, but we are (at some point, not when) moving to a static HTML generator. I'm not close to the doc generation/writing, so I don't know too much.

jph• 11 years ago

We recently evaluated RAML, Swagger, and Blueprint.

RAML was the top choice for developer preference and syntax, but industry tooling was much stronger for Swagger.

What we chose was Swagger 2 with the new options for YAML syntax, which gives us good readability/writeability, plus excellent tooling.

sinzone• 11 years ago

Order of mainstream adoption for API description languages:

1) Swagger (by far)

2) API Blueprint

3) RAML

mpdehaan23• 11 years ago

It might be nice if this was described in an existing data format (YAML, anyone) as a particular form of structure, rather than inventing a new data format.

pksunkara2• 11 years ago

What do you think about API Blueprint [1]? It is based on Markdown.

[1] https://apiblueprint.org

mpdehaan23• 11 years ago

I think Markdown is generally unsuitable as a data format for machines.

YAML strikes a nice balance between machines and people, but I wouldn't want to write a blog post in it.

Markdown is great for blog posts, but APIs are terse.

rlevy2• 11 years ago

RAML is essentially a YAML with a specific schema. Tell your IDE to treat .raml files as .yaml and all the syntax highlighting, etc will work perfect

mpdehaan23• 11 years ago

Ah, that makes a lot more sense then.

It appeared to have weirdness from the homepage:

  - secured: !include http://remote-host/secured.yml

/songs:

Which is invalid YAML.

It turns out this is probably an unfortunate word-wrap in the page, where a non-wrapping text field would better convey the format.

lighthawk2• 11 years ago

It's nice, but because of the HAML-like format, there are a lot of empty space characters included.

That's great for readability, but it doesn't seem like a perfect choice for a webservice description language, since that content might get hosted and transferred often over the network for clients that might be interested in it.

You could convert to binary to compress it, but that makes it harder for the client, so the friendliest thing would be to convert it to JSON, e.g.: http://my.host/to/a/path/of/my_service.haml.json in addition to the more human-readable haml format at: http://my.host/to/a/path/of/my_service.haml

robbs• 11 years ago

If size is a concern, have your webserver gzip it.

https://en.wikipedia.org/wiki/HTTP_compression

lighthawk2• 11 years ago

You should probably have a format that is easily digestible, like WSDL was for SOAP services. Requiring the person serving the RAML to setup their webserver to gzip it and requiring the client to gunzip everything is not very friendly. Having a JSON version of the spec would condense it while still allowing it to be readable, and it would be easily digestible in Javascript and many other languages without an additional parser.

curiousjorge• 11 years ago

RAML was first proposed in 2013. The initial RAML specification was authored by Uri Sarid, Emiliano Lesende, Santiago Vacas, and Damian Martinez. Development is managed by the RAML Workgroup.[4]

how do you create your own "specification" and your own "workgroup"? Can anyone invent some acronym, create their own "workgroup"? Do you need some blessings from YAML or someone else?

dragonwriter4• 11 years ago

how do you create your own "specification" and your own "workgroup"?

You create a specification by recording requirements in some medium.

You create a workgroup by getting a bunch of people to work together.

Can anyone invent some acronym, create their own "workgroup"?

Yes. Whether other people care that they have done so or not is another question.

Do you need some blessings from YAML or someone else?

No.

danellis3• 11 years ago

This completely misses the point of REST. By miles.

Why not just call it an "HTTP API modeling language", since that's what it is, instead of using buzzwords for the sake of it?

SeldomSoup2• 11 years ago

How does this miss the point of REST?

danellis3• 11 years ago

It describes how to construct URLs to get from one state to another (e.g. from a base URL to a list of songs, or from the list to an individual song). REST URLs are supposed to be opaque. A RESTful resource should provide links to its related resources for the user agent to navigate.

There's nothing wrong with what the author is trying to do, but it's nothing to do with REST.

dragonwriter4• 11 years ago

How does this miss the point of REST?

Because if it didn't, the full API description language would be:

  api-root: <url>

Or, for a pedantically detailed version:

  api-root: <url>
  media-types: 
      - <media-type>
      - <media-type>

dragonwriter4• 11 years ago

The APIs modeled by this language are not RESTful: in fact, the use of this type of WSDL-like description is the antithesis of the hypertext-centric core concept of REST.

Calling this a "RESTful API modeling language" is like calling a water cannon a flamethrower. If we're going to call this RESTful, we might as well call SOAP RESTful.

Pyxl101• 11 years ago

Indeed. REST has come to mean almost the antithesis of what it was created to mean. Roy Fielding wrote about this topic, clarifying common misconceptions and what REST APIs are not:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

The need for a document like this in the first place demonstrates that the API is not REST. These systems are simply ad hoc, partially specified RPC systems operating over HTTP.

I've almost given up caring about what REST means due to endless debates and misunderstandings about this. REST just means any HTTP-based API where operations and inputs/outputs are modeled with HTTP fields these days.

mohsen1• 11 years ago

One important difference between RAML and Swagger is that Swagger is not owned by a single company. Swagger working group is working on an open governance model to make it even more vendor neutral. Everything about Swagger is open.

Disclaimer: I'm working on Swagger on behalf of Apigee.

timothycrosley• 11 years ago

It would take less time, and you would get more documentation by using something like hug: https://github.com/timothycrosley/hug

while actually allowing you to build RESTful APIs

RAML – RESTful API modeling language

Related Stories