from Hacker News

RAML - RESTful API modeling language

by DanI-S on 10/2/13, 4:20 PM with 55 comments

• by jalfresi on 10/2/13, 6:31 PM

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

• by Terretta on 10/2/13, 7:26 PM

  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.

• by rgbrgb on 10/2/13, 5:24 PM

  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/

• by mcguire on 10/2/13, 8:59 PM

  First, this seems to view the URLs as primary. They aren't. The document formats are the most important part, even if you are doing a http-rpc style, not-really-REST interface.

  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?

• by taeric on 10/2/13, 5:44 PM

  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.

• by zzen on 10/2/13, 7:14 PM

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

• by jamespitts on 10/2/13, 7:41 PM

  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.

• by ImJasonH on 10/2/13, 7:35 PM

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

• by publicfig on 10/2/13, 5:13 PM

  Man, that page is hard to read.

• by madisp on 10/2/13, 5:46 PM

  Now all we are missing is a code generator that generates a stubbed site based on the raml spec...

• by rektide on 10/2/13, 5:42 PM

  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.

• by louischatriot on 10/2/13, 5:16 PM

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

• by phamilton on 10/3/13, 3:11 PM

  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?

• by grogenaut on 10/2/13, 4:55 PM

  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.

• by nickporter on 10/2/13, 7:39 PM

  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

• by viblo on 10/3/13, 3:57 AM

  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.

• by nfoz on 10/3/13, 4:46 AM

  Really? Dark gray until mouse hover makes different paragraphs glow???

  web devs, whyyyyy

• by mishkinf on 10/2/13, 7:53 PM

  https://github.com/mishkinf/apiknow is another project to help build out an api documentation and Test Drive it

• by crazychrome on 10/2/13, 9:34 PM

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

• by tylermauthe on 10/3/13, 5:56 AM

  HATEOAS or bust.