Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

RAML - RESTful API modeling language

raml.org

Post reply on HN
Print view View original

21–30 of 57 posts

Re: RAML - RESTful API modeling language

#21

Post by Terretta »

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.

Re: RAML - RESTful API modeling language

#22

Post by ImJasonH »

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

Re: RAML - RESTful API modeling language

#24

Post by jamespitts »

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.

Re: RAML - RESTful API modeling language

#25

Post by zzen »

jamespitts wrote: post #24

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

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.

Re: RAML - RESTful API modeling language

#27

Post by inerte »

mishkinf wrote: post #26

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/

Re: RAML - RESTful API modeling language

#28

Post by tootie »

jalfresi wrote: post #14

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

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.

Re: RAML - RESTful API modeling language

#29

Post by smizell »

jalfresi wrote: post #14

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

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.

Re: RAML - RESTful API modeling language

#30

Post by dragonwriter »

tootie wrote: post #28
jalfresi wrote: post #14

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

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.

Post reply on HN