RAML – RESTful API modeling language | Hacker News Reader

RAML – RESTful API modeling language

raml.org

80 pointstilt57 comments

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.

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

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.

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.

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.

There's also the swagger spec:

http://swagger.io/

I have used swagger in multiple projects with great success.

Are any of those projects open source? I'm looking for an example Swagger YAML/JSON file that includes authentication.

https://github.com/zalando-stups/pierone/blob/master/resourc...

PierOne is a Docker registry in Clojure with S3 backend and OAuth support. I wrote swagger1st[0] which is used there. Swagger supports authorization definitions via scopes. Besides that, you can only define required basic auth or API key usage for authentication but not for authorisation.

Swagger defines various places, where you can add own x-* attributes to fill in your own logic if swagger is not expressive enough.

[0] https://github.com/sarnowski/swagger1st

Awesome. Thanks for sharing!

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

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

https://github.com/crowdwave/serve_swagger

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

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.

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.

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?

How does this miss the point of REST?

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.

Oops. That's one detail I missed in all those API tutorials. Thanks.

The canonical source is Roy Fielding's thesis, in particular chapters 5 and 6.

https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

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

Are there any extant REST API's for which one could programmatically generate a client library based purely upon the root URL and media types?

https://www.ietf.org/rfc/rfc5023.txt

This is a great question. Any answers would be illuminating. I've largely given up on the idea of hypermedia APIs that work like this, because the mindshare and tooling just doesn't appear to be there for it. I've never seen a client library that is based on following rels from a root, rather than generating URLs based on out-of-band information.

> Are there any extant REST API's for which one could programmatically generate a client library based purely upon the root URL and media types?

For a truly RESTful API, the question you ask is somewhat incoherent. A client for a RESTful API consists of two key sets of components: functionality for sending and receiving resource representations to and from locations identified by URIs, and functionality for handling resource representations of particular media types. Assuming you have those, you don't need to "programmatically generate a client library" with the particular base URL of a particular API root, you access a URL that provides resources of any of the supported media types and your off to the races without programmatically generating anything.

Is this possible in practice for real implementations of RESTful principles? Yes, including the one that motivated the articulation of the REST principles, the WWW.

Is REST appropriate for all APIs? Maybe, maybe not. But its probably not useful to anyone to just call every web service that uses HTTP and isn't SOAP "RESTful".

Sure, for consuming the API - but does RAML have to be used this way? Couldn't RAML be used to generate test expectations or even (with tooling that probably doesn't exist) actually generate the API itself?

Devil's advocate: "api-root: http://example.org/foo.raml" fits that bill.

Order of mainstream adoption for API description languages:

1) Swagger (by far)

2) API Blueprint

3) RAML

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

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

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

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.

What server or client toolchains are you using that don't make HTTP Compression trivial and transparent?

If you're dead set on using JSON, note that RAML seems to be a subset of YAML, which can be easily converted to JSON. You could do that on the server side, or just use one of the many YAML parsers written in javascript on the client side.

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.

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.

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.

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.

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

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

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

Very cool, it feels like WSDL for REST

EDIT: spelling

WSDL :-)

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.

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

Our hope is that we can combine HATEOAS with an ontology to create autonomous clients and, otherwise, provide rich enough metadata in each resource to generate an appropriate UI (for human facing clients); the 'semantic web' approach.

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.

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

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.

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

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

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.

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

[1]: https://apiblueprint.org

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.

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

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.

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

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

Reply on news.ycombinator.com