RAML – RESTful API modeling language

[roguelynn]

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]

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

[dragonwriter]

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]

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.

[jwingy]

There's also the swagger spec:

http://swagger.io/

[rlevy]

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.

[gsibble]

I have used swagger in multiple projects with great success.

[andrewstuart]

This might be of interest - generates Python/Falcon API server from Swagger spec.

https://github.com/crowdwave/serve_swagger

[joesmo]

Swagger has a lot more backing / support amongst API proxy providers as well.

[jzsprague]

i used to use raml and still actually prefer it to swagger, but find that swagger is much more widely supported.

[jph]

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.

[danellis]

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?

[SeldomSoup]

How does this miss the point of REST?

[sinzone]

Order of mainstream adoption for API description languages:

1) Swagger (by far)

2) API Blueprint

3) RAML

[lighthawk]

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]

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

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

[joslin01]

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.

[mohsen1]

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.

[CookWithMe]

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.

[pksunkara]

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

[pavel_pt]

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.

[earth2marsh]

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

[swalsh]

Very cool, it feels like WSDL for REST

EDIT: spelling

[aikah]

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 ...

[pavel_pt]

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.

[Xophmeister]

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.

[sgolestane]

WSDL :-)

[timothycrosley]

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

[mpdehaan2]

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.

[pksunkara]

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

[1]: https://apiblueprint.org

[rlevy]

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

[curiousjorge]

>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?

[dragonwriter]

> 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.