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