
RAML – RESTful API modeling language - tilt
http://raml.org/
======
roguelynn
I wrote a Python parser for this called RAMLfications
([https://ramlfications.readthedocs.org/en/latest/](https://ramlfications.readthedocs.org/en/latest/))

I actually built the API console for my company - Spotify
([https://developer.spotify.com/web-
api/console/](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](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/](https://developer.spotify.com/web-api/get-album/)

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

------
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...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

> 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/](http://swagger.io/)

~~~
gsibble
I have used swagger in multiple projects with great success.

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

~~~
sarnowski
[https://github.com/zalando-
stups/pierone/blob/master/resourc...](https://github.com/zalando-
stups/pierone/blob/master/resources/api/pierone-api.yaml)

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](https://github.com/sarnowski/swagger1st)

~~~
Abundnce10
Awesome. Thanks for sharing!

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

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

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

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

------
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](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](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](https://en.wikipedia.org/wiki/HTTP_compression)

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

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

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

~~~
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
Swagger added support for examples with version 2.0 of the format, see:
[https://github.com/swagger-api/swagger-
spec/blob/master/vers...](https://github.com/swagger-api/swagger-
spec/blob/master/versions/2.0.md#example-object)

------
swalsh
Very cool, it feels like WSDL for REST

EDIT: spelling

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

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

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

------
timothycrosley
It would take less time, and you would get more documentation by using
something like hug:
[https://github.com/timothycrosley/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](https://apiblueprint.org)

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

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

