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

31–40 of 59 posts

Re: RAML – RESTful API modeling language

#31

Post by earth2marsh »

CookWithMe wrote: post #8

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

If you're interested in re-use in Swagger, see the guidelines here: https://github.com/swagger-api/swagger-spec/blob/master/guid...

Re: RAML – RESTful API modeling language

#34

Post by lighthawk »

robbs wrote: post #30
lighthawk wrote: post #26

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

If size is a concern, have your webserver gzip it. https://en.wikipedia.org/wiki/HTTP_compression

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.

Re: RAML – RESTful API modeling language

#35

Post by lotyrin »

lighthawk wrote: post #34
robbs wrote: post #30

Earlier quoted context omitted.

If size is a concern, have your webserver gzip it. https://en.wikipedia.org/wiki/HTTP_compression

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

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

Re: RAML – RESTful API modeling language

#36

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

Re: RAML – RESTful API modeling language

#38

Post by openasocket »

lighthawk wrote: post #34
robbs wrote: post #30

Earlier quoted context omitted.

If size is a concern, have your webserver gzip it. https://en.wikipedia.org/wiki/HTTP_compression

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

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.

Re: RAML – RESTful API modeling language

#39

Post by danellis »

SeldomSoup wrote: post #33
danellis wrote: post #32

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?

How does this miss the point of REST?

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.

Re: RAML – RESTful API modeling language

#40

Post by pksunkara »

CookWithMe wrote: post #8

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

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.

[1]: https://apiblueprint.org

Post reply on HN