RAML - RESTful API modeling language(raml.org)
raml.org
RAML - RESTful API modeling language
http://raml.org/
21 comments
So a lot of people here hate this. I'm not a huge fan, but I want to understand the right way to solve the problem. The problem I see with the APIs I work on is that automated integration tests are hard. I would love a way to answer the questions "Am I sending a request in the right format?" as well as "Am I going to receive data in the form I expect?". If I had a JSON schema or something, I could include those tests in isolation rather than in a big system test environment.
So it sounds like true REST is supposed to solve that. How?
So it sounds like true REST is supposed to solve that. How?
It would be interesting to hear some reasoning from the RAML people about what it brings compared to existing solutions like Swagger. From a quick look it seems like they solve the same thing except that RAML use yaml and is much more immature.
In short, we wanted an API spec that was much more readable and efficient, showed the structure of the API more clearly, and promoted consistency and reuse. We wanted an API spec that was intuitive enough to just type out in an editor when designing an API. And we iterated on it quite a bit in real-world cases to be really convinced it was worth introducing this different approach.
Really? Dark gray until mouse hover makes different paragraphs glow???
web devs, whyyyyy
web devs, whyyyyy
I can understand the intent: showing exactly which parts of the document match up with the section descriptions. That itself is not a bad idea.
But making all of it dark gray (so, intended to be not-visible) by default is really silly.
But making all of it dark gray (so, intended to be not-visible) by default is really silly.
i'd say it's a wrong direction, or at least a premature optimization. it smells like WSDL/SOAP, UML and other attempts to create a layer of abstraction which is too high level to be useful while not insightful enough for conceptualization, and too prescriptive to be practical.
how about further narrow down the scope, e.g. only focus on describe relationship among apis (how a song api related to album, musician apis)?
how about further narrow down the scope, e.g. only focus on describe relationship among apis (how a song api related to album, musician apis)?
HATEOAS or bust.
It burns the eyes!
Also, put a simple example on the main github page and don't make me go scavenge through 8 links to find out what the thing is.
Also, put a simple example on the main github page and don't make me go scavenge through 8 links to find out what the thing is.
Man, that page is hard to read.
Especially if you are a skim reader, that grey to bright colour jump just ma me loose my place, and made it impossible to refer back. Probably the worst document page I've ever tried to read :/
Did you try mouse-hovering over paragraphs?
The content should be good enough that it can stand on its own instead of trying to be flashy. A simple doc and tutorial would have been sufficient.
I found the contrast of colours on the website almost unreadable.
I found the contrast of colours on the website almost unreadable.
for me that is what made it difficult, I wanted to see the example in its entirety without having to hover back and forth. The hover "highlight" should be a "oh thats nice" interaction - not a required step for reading.
Agreed, I shouldn't have to constantly move the mouse around just to read the page.
So hard to read. Also, do we really need another modelling language? UML was not enough?
(not saying ML could be used to do that, more like "didn't we learn with UML that these kind of stuff brings pain and no benefits")
(not saying ML could be used to do that, more like "didn't we learn with UML that these kind of stuff brings pain and no benefits")
For those interested in this type of thing, Apiary is building a platform that generates a mock server based on a similar specification language: http://apiary.io/
I for one don't mind the style, don't mind the media experience nor do I mind having one. It's distinct and unique and not hard to read for me, and perhaps even a modicrum of useful- bringing sessions into focus.
It is, however, entirely mobile hostile.
It is, however, entirely mobile hostile.
Is there any reason to think that this will be better than wsdl style descriptions? To wit, WADL tried this, but it seems to have stalled heavily.
I should add I do not find WSDL/WADL as horrible as it could be. There is something nice about being able to generate a client in one of any given number of languages that can hit a service. Sorta sucks when you can't do that with a traditional workflow in REST.
I should add I do not find WSDL/WADL as horrible as it could be. There is something nice about being able to generate a client in one of any given number of languages that can hit a service. Sorta sucks when you can't do that with a traditional workflow in REST.
Personally I think WSDL is an eldritch abomination that I utterly loath - for the sake of "generating a client" you can end up with a opaque mess that can be very difficult to diagnose problems with - particularly when different technology platforms are used on the client and server.
I never thought I'd say this, but I actually had fewer problems with CORBA and ONC RPC based systems than SOAP/WSDL based web services. Probably because they were so limiting that the interfaces tended to be quite straightforward - rather than the baroque approach often favoured by "enterprise" web services.
I will happily sacrifice a bit of development time for something that is much easier to troubleshoot - give me RESTful web services any day.
I never thought I'd say this, but I actually had fewer problems with CORBA and ONC RPC based systems than SOAP/WSDL based web services. Probably because they were so limiting that the interfaces tended to be quite straightforward - rather than the baroque approach often favoured by "enterprise" web services.
I will happily sacrifice a bit of development time for something that is much easier to troubleshoot - give me RESTful web services any day.
Oh, no doubt that there were terribly done WSDL mechanisms out there. Probably most of them. However, many of the mature choices now have a fairly reliable "generate a client off of this wsdl" to get a generic api you can hit from your language of choice. I recall using python and such was actually mostly as expected.
Compared with most "RESTful" services, which require me personally figuring out everything and home growing every portion. Heaven help you if someone makes a change breaking something you had already done.
Compared with most "RESTful" services, which require me personally figuring out everything and home growing every portion. Heaven help you if someone makes a change breaking something you had already done.
in what ways did you find corba/idl more limited than soap/wsdl?
Not so much that Corba/IDL were intrinsically more limited than SOAP/WSDl - more that they were less tightly integrated with development environment and platforms so generally, in my experience, seemed to be used with a bit more care.
Now all we are missing is a code generator that generates a stubbed site based on the raml spec...
Or how about an angular service that parses a raml file and returns a resource that implements up all models and methods ?
No need to stub it, just generate it on the fly.
Server side too. At least for quickly iterating and hand implement only the methods that require special handling.
No need to stub it, just generate it on the fly.
Server side too. At least for quickly iterating and hand implement only the methods that require special handling.
Or just not reinvent the wheel and use SOAP. Pretty much what this thing is with a little less cruft.
[deleted]
I dont understand what the purpose of this is. I thought the whole point of REST is that it is discoverable at runtime. If you have an "API Spec" doesnt that mean the server owner is now beholden to that spec; that changes to their resources would break compatability with any client written to conform to the spec?
I thought everything you needed to write a REST API client is included in the media-type specification and the rel profile?
For example, the spec for the HTML media-type details that link elements with the rel type of "stylesheet" should be resolved by HTTP GET.
My understanding was that (in the example given) you write a spec for your music description media-type e.g. MUSICML, and register it with IANA (because media-types MUST be registered with a central authority). Then your client only need make a HTTP OPTIONS request to see that the Content-Type e.g. vnd.example.com/musicml+v1.0 and the methods allowed on that resource.
As long at the client uses the described rel profiles appropriate to the media-type MUSICML e.g. the spec specifies that the rel type "play" should HTTP GET the specified WAV file and play it in the client, then the server owner is free to modify the API endpoints as they wish.
I never understood why people insist in adding more layers of cruft on top of a perfectly adequate transfer protocol (HTTP) that is almost always worse and brittle than what the existing protocol already provides.
(don't get me wrong, I appreciate that hardly anyone does rest properly, but that doesnt mean WSDL-flavour-of-the-month will have as much uptake as HTTP itself!)
I thought everything you needed to write a REST API client is included in the media-type specification and the rel profile?
For example, the spec for the HTML media-type details that link elements with the rel type of "stylesheet" should be resolved by HTTP GET.
My understanding was that (in the example given) you write a spec for your music description media-type e.g. MUSICML, and register it with IANA (because media-types MUST be registered with a central authority). Then your client only need make a HTTP OPTIONS request to see that the Content-Type e.g. vnd.example.com/musicml+v1.0 and the methods allowed on that resource.
As long at the client uses the described rel profiles appropriate to the media-type MUSICML e.g. the spec specifies that the rel type "play" should HTTP GET the specified WAV file and play it in the client, then the server owner is free to modify the API endpoints as they wish.
I never understood why people insist in adding more layers of cruft on top of a perfectly adequate transfer protocol (HTTP) that is almost always worse and brittle than what the existing protocol already provides.
(don't get me wrong, I appreciate that hardly anyone does rest properly, but that doesnt mean WSDL-flavour-of-the-month will have as much uptake as HTTP itself!)
I think the different definitions for REST have really muddied the water. To the REST purist, RAML is falling well short of being truly RESTful for reasons which you've mentioned. In other words, RAML isn't REST at all. To most others, REST is simply another RPC, like SOAP (hence all of the comments saying this is not much better than SOAP). Those of the latter thinking need someway to describe how their API should be consumed other than hypermedia types, so specs like RAML are born.
On their site, they say, "RAML isn't strict: in the end it is only describing HTTP with a few higher-level (optional) constructs." Looks like it's aiming to describe HTTP and URLs rather than hypermedia types.
On their site, they say, "RAML isn't strict: in the end it is only describing HTTP with a few higher-level (optional) constructs." Looks like it's aiming to describe HTTP and URLs rather than hypermedia types.
> I thought the whole point of REST is that it is discoverable at runtime.
Yes. This is about the kind of pseudo-REST that is sometimes called RESTful and has nothing to do with REST as it iis just a plain HTTP-based API.
Yes. This is about the kind of pseudo-REST that is sometimes called RESTful and has nothing to do with REST as it iis just a plain HTTP-based API.
Yeah, and I see that approach mostly failing. The notion of resource-orientation and HTTP verbs is really useful, but being true to Fielding's dream is not a priority for most organizations. Stronger typing and explicit descriptors are really useful in an enterprise environment.
If we want a non-RESTful (in the strict sense) solution with those particular enterprise features, we have SOAP+WSDL.
Reinventing the wheel and calling it RESTful is non-helpful (because, again, we have a mature infrastructure of tools filling that need in the SOAP+WSDL space, so if we don't need a new approach, it would be more efficient to use them rather than rebuild them, and if we do need a new approach, well, reinventing SOAP isn't it.)
REST does offer solutions to those problems, but these pseudo-REST approaches drop exactly the pieces that address those concerns and replace them with approaches based on the way earlier, pre-REST, systems approached the problem. Which amounts to throwing out the core of REST for no gain over just using the earlier technologies.
Reinventing the wheel and calling it RESTful is non-helpful (because, again, we have a mature infrastructure of tools filling that need in the SOAP+WSDL space, so if we don't need a new approach, it would be more efficient to use them rather than rebuild them, and if we do need a new approach, well, reinventing SOAP isn't it.)
REST does offer solutions to those problems, but these pseudo-REST approaches drop exactly the pieces that address those concerns and replace them with approaches based on the way earlier, pre-REST, systems approached the problem. Which amounts to throwing out the core of REST for no gain over just using the earlier technologies.
SOAP is RPC. It's fundamentally different. REST is not completely undone just because you want validation. Without a schema or DDL, you're still validating but you're doing it in code.
> SOAP is RPC.
Yes.
> It's fundamentally different.
It's fundamentally different than REST, sure. Its not fundamentally different than "REST" that abandons resource-oriented hypermedia.
> REST is not completely undone just because you want validation.
REST includes a validation model (indeed, its centered around one.)
It is completely undone when you toss that out and replace it with a different one.
> Without a schema or DDL, you're still validating but you're doing it in code.
With a schema or DDL, you are validating in code. It may be code in an external library or tool, but that's just a possibility with any validation model, whether its Schema-based, or Media-type-based (as in REST), or based on something else.
Yes.
> It's fundamentally different.
It's fundamentally different than REST, sure. Its not fundamentally different than "REST" that abandons resource-oriented hypermedia.
> REST is not completely undone just because you want validation.
REST includes a validation model (indeed, its centered around one.)
It is completely undone when you toss that out and replace it with a different one.
> Without a schema or DDL, you're still validating but you're doing it in code.
With a schema or DDL, you are validating in code. It may be code in an external library or tool, but that's just a possibility with any validation model, whether its Schema-based, or Media-type-based (as in REST), or based on something else.
A schema allows for declarative validation and allows it to be defined once and once per consumer.
A well-defined media-type does much the same thing and is what REST is centered on.
An API based on HTTP and schemas rather than media types for content definition/validation is more like SOAP than REST.
OTOH, an API based on resource-oriented hypermedia could incidentally use media types that are defined in terms of schemas, and still be REST.
An API based on HTTP and schemas rather than media types for content definition/validation is more like SOAP than REST.
OTOH, an API based on resource-oriented hypermedia could incidentally use media types that are defined in terms of schemas, and still be REST.
(disclaimer, I'm founder of Apiary, which started apiblueprint.org)
I'm happy that Mulesoft are getting on the "better, human readable API DSL" bandwagon. It's very important.
At Apiary we found that embedding one format (Markdown, for human-readable documentation) into another format (YAML, for structured parseable data) is hard for the consumer, tough for the text editors/IDEs/syntax highlighters and ultimately useless. That's why apiblueprint.org is PURE markdown, that displays well on GitHub, has great syntax-highlighting support in your editor - and is just as parseable (since we ship an MIT-licensed parser with it).
I wish we could've united on a single format, but I guess the stronger will win and a little competition is always good for the end-users.
I'm happy that Mulesoft are getting on the "better, human readable API DSL" bandwagon. It's very important.
At Apiary we found that embedding one format (Markdown, for human-readable documentation) into another format (YAML, for structured parseable data) is hard for the consumer, tough for the text editors/IDEs/syntax highlighters and ultimately useless. That's why apiblueprint.org is PURE markdown, that displays well on GitHub, has great syntax-highlighting support in your editor - and is just as parseable (since we ship an MIT-licensed parser with it).
I wish we could've united on a single format, but I guess the stronger will win and a little competition is always good for the end-users.
> I wish we could've united on a single format, but I guess the stronger will win and a little competition is always good for the end-users.
the (open source) tooling is what makes or breaks adoption of languages like these, and neither of them has much to offer in that regard. apiblueprint has code for node and .net, raml doesn't even list libraries that can parse it. contrast that with json schema: there's an rfc standard and libs that handle validation in almost every widely-used general-purpose language...
... and that's just the bare minimum of tooling i would hope for from a popular standard. i'd be much more psyched to find an equivalent library of <http://www.rexx.com/~dkuhlman/generateDS.html> for jsonschema than i am to see yet another domain specific language with bad/no tooling. a standard without an implementation is nothing more than a suggestion -- and one that is unlikely to be strictly adhered to.
the (open source) tooling is what makes or breaks adoption of languages like these, and neither of them has much to offer in that regard. apiblueprint has code for node and .net, raml doesn't even list libraries that can parse it. contrast that with json schema: there's an rfc standard and libs that handle validation in almost every widely-used general-purpose language...
... and that's just the bare minimum of tooling i would hope for from a popular standard. i'd be much more psyched to find an equivalent library of <http://www.rexx.com/~dkuhlman/generateDS.html> for jsonschema than i am to see yet another domain specific language with bad/no tooling. a standard without an implementation is nothing more than a suggestion -- and one that is unlikely to be strictly adhered to.
Sure, API Blueprint supports JSON Schema. If you're happy to put in the effort, nothing stops you from using JSON Schema in the blueprint and all the tooling built on top of it.
but that's my point: there isn't as much library support as there ought be, even for json schema, let alone these newer domain-specific languages that incorperate/extend json schema.
sometimes i think it would make just as much if not sense to define these communication protocols with a bnf grammar (for endpoints and response codes) or to use s-expressions (since json is pretty much just sugared lisp) or some other well-worn-but-adaptable format just because there are already parser generators and scheme interpreters written for every language.
sometimes i think it would make just as much if not sense to define these communication protocols with a bnf grammar (for endpoints and response codes) or to use s-expressions (since json is pretty much just sugared lisp) or some other well-worn-but-adaptable format just because there are already parser generators and scheme interpreters written for every language.
couldn't agree more that it ain't much without tooling -- RAML's been out for only about 24 hours, but open-source tooling is right around the corner (weeks, not months).
Regarding tooling.. check out the video that just went up on http://raml.org (and on Youtube: http://youtu.be/5o_nExedezw)
(disclaimer, I'm from the RAML workgroup -- nice to see you here, Jakub!)
As you know, we carefully considered swagger and blueprint, before embarking on the RAML path. There's a bunch of us who are strong believers in very human-readable API specs, though we also strongly believe in clean API specs that reveal the structure of the API and encourage consistency and reuse -- and we just didn't find that in existing DSLs.
We're actually not finding any issues embedding markdown documentation in RAML at just those points in the spec that need documentation, while letting the spec itself do the talking when more documentation would just be repetitive. That way the structure of the API is manifest.
We also find the spec to be much DRYer in RAML than other ways; less repetitive reading means quicker and better grokking of the API.
I think the point about syntax highlighting in generic editors is debatable, but that's fine -- as you say, we have two different approaches and we'll keep each other on our toes, to the benefit of the community. Apiary's dedication to user experience is an inspiration to us. And just in case, my invitation to you to consider collaborating with us and the other workgroup members on RAML remains very much open.
As you know, we carefully considered swagger and blueprint, before embarking on the RAML path. There's a bunch of us who are strong believers in very human-readable API specs, though we also strongly believe in clean API specs that reveal the structure of the API and encourage consistency and reuse -- and we just didn't find that in existing DSLs.
We're actually not finding any issues embedding markdown documentation in RAML at just those points in the spec that need documentation, while letting the spec itself do the talking when more documentation would just be repetitive. That way the structure of the API is manifest.
We also find the spec to be much DRYer in RAML than other ways; less repetitive reading means quicker and better grokking of the API.
I think the point about syntax highlighting in generic editors is debatable, but that's fine -- as you say, we have two different approaches and we'll keep each other on our toes, to the benefit of the community. Apiary's dedication to user experience is an inspiration to us. And just in case, my invitation to you to consider collaborating with us and the other workgroup members on RAML remains very much open.
When looking at the concept, it's interesting to me how much the pseudo code looks like a real REST API handler written in a state machine DSL.
Decision graph: http://clojure-liberator.github.io/liberator/tutorial/decisi...
Actual code: http://clojure-liberator.github.io/liberator/tutorial/all-to...
Progenitor = Erlang Webmachine: https://github.com/basho/webmachine/wiki/Overview
I'd rather write a working API than this separate spec language. By writing your 'spec' as a state machine, you get REST formality and consistency, plus, well, you now have something that works.
OTOH, running an existing API through something that would generate this RAML document could be very interesting as a way to make sure everyone's on the same page in a language neutral way.
Decision graph: http://clojure-liberator.github.io/liberator/tutorial/decisi...
Actual code: http://clojure-liberator.github.io/liberator/tutorial/all-to...
Progenitor = Erlang Webmachine: https://github.com/basho/webmachine/wiki/Overview
I'd rather write a working API than this separate spec language. By writing your 'spec' as a state machine, you get REST formality and consistency, plus, well, you now have something that works.
OTOH, running an existing API through something that would generate this RAML document could be very interesting as a way to make sure everyone's on the same page in a language neutral way.
I like to think design-first and if possible in the most minimal fashion that captures the interface, but I certainly see (and share) the appeal of writing working code. In many cases like that (including APIs that are already implemented in code), generating a clean RAML spec from the code is a good way of capturing the interface itself, in a very readable way that shows the structure. Thanks for these links -- very interesting!
This seems similar to Google's Discovery Service (https://developers.google.com/discovery/) which describes all new Google APIs in a JSON document.
This powers the online APIs Explorer (https://developers.google.com/apis-explorer) and code generators (e.g., https://code.google.com/p/google-api-go-client/source/browse...)
APIs created using Cloud Endpoints on App Engine also generate a Discovery document for their APIs (https://developers.google.com/appengine/docs/java/endpoints/)
This powers the online APIs Explorer (https://developers.google.com/apis-explorer) and code generators (e.g., https://code.google.com/p/google-api-go-client/source/browse...)
APIs created using Cloud Endpoints on App Engine also generate a Discovery document for their APIs (https://developers.google.com/appengine/docs/java/endpoints/)
I'd like to see more of these things!
I feel like a REST API is the interface, and a web app is just the implementation. Makes sense to separate the two.
Although somewhat unrelated, this reminds me of https://thrift.apache.org
I feel like a REST API is the interface, and a web app is just the implementation. Makes sense to separate the two.
Although somewhat unrelated, this reminds me of https://thrift.apache.org
Standards like this enable new value, but make it harder for newcomers. Worse, they add a lot of burdensome work in situations where implementation or compliance is demanded of developers.
Complexity-enabling standards are often a sign that a funky, little nook of software is maturing. It is a sign of huge success, too, because new layers are beckoning to lay on top of an old layer.
We had a good run with REST and JSON, which managed to hold back corporate software engineering culture -- represented in standards like SOAP and WSDL -- for a very long time. No doubt there is a future even with "complexification", but I think that new alternatives will come soon into the fray.
Complexity-enabling standards are often a sign that a funky, little nook of software is maturing. It is a sign of huge success, too, because new layers are beckoning to lay on top of an old layer.
We had a good run with REST and JSON, which managed to hold back corporate software engineering culture -- represented in standards like SOAP and WSDL -- for a very long time. No doubt there is a future even with "complexification", but I think that new alternatives will come soon into the fray.
Personally, I believe there is a way to enable new value while fighting back the complexity and corporate engineering culture.
REST needs to mature and get tooling. But we need to avoid the WSDL complexity.
REST needs to mature and get tooling. But we need to avoid the WSDL complexity.
Totally agree on both points...
There's nothing like creating within a clear, clutter-free space. This is what partly drives the enthusiasm when some new hotness hits the dev scene. Other drivers include liberation from gatekeepers and previous decisions.
The possibilities seem endless and it encourages creativity, even if you have to do some nasty bootstrapping to get there.
There's nothing like creating within a clear, clutter-free space. This is what partly drives the enthusiasm when some new hotness hits the dev scene. Other drivers include liberation from gatekeepers and previous decisions.
The possibilities seem endless and it encourages creativity, even if you have to do some nasty bootstrapping to get there.
Good luck avoiding complexity when you hit P2P security, transactions, etc.
https://github.com/mishkinf/apiknow is another project to help build out an api documentation and Test Drive it
I think Swagger [1,2] is similar, which I am currently using, via node/restify. Awesome little project that generates docs and an interface for API consumers to experiment with.
1 - https://developers.helloreverb.com/swagger/ 2 - http://swagger.wordnik.com/
1 - https://developers.helloreverb.com/swagger/ 2 - http://swagger.wordnik.com/
How does Swagger compare with Scrooge (Twitter's Scala / Apache Thrift code generator)[0]?
[0] http://twitter.github.io/scrooge/
[0] http://twitter.github.io/scrooge/
Second, YAML? Haven't we already learned that markup languages don't make good programming languages? (That's what this is, right? Nobody is really going to use it to document an API, any more than anyone uses WSDL for more than generating stubs.)
Third (and not really germane), JSON schemas? Describing the format of JSON documents, in JSON? Because XML schemas are so wonderful?