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

41–50 of 59 posts

Re: RAML – RESTful API modeling language

#41

Post by rlevy »

jwingy wrote: post #2

There's also the swagger spec: http://swagger.io/

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.

Re: RAML – RESTful API modeling language

#42

Post by pksunkara »

mpdehaan2 wrote: post #25

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.

What do you think about API Blueprint [1]? It is based on Markdown.

[1]: https://apiblueprint.org

Re: RAML – RESTful API modeling language

#43

Post by rlevy »

mpdehaan2 wrote: post #25

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 is essentially a YAML with a specific schema. Tell your IDE to treat .raml files as .yaml and all the syntax highlighting, etc will work perfect

Re: RAML – RESTful API modeling language

#44

Post by dragonwriter »

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?

> How does this miss the point of REST?

Because if it didn't, the full API description language would be:

  api-root:
Or, for a pedantically detailed version:

  api-root: 
  media-types: 
      - 
      -

Re: RAML – RESTful API modeling language

#45

Post by philwelch »

dragonwriter wrote: post #44
SeldomSoup wrote: post #33

Earlier quoted context omitted.

How does this miss the point of REST?

> How does this miss the point of REST? Because if it didn't, the full API description language would be: api-root: Or, for a pedantically detailed version: api-root: media-types: - -

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?

Re: RAML – RESTful API modeling language

#46

Post by dragonwriter »

curiousjorge wrote: post #28

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

> how do you create your own "specification" and your own "workgroup"?

You create a specification by recording requirements in some medium.

You create a workgroup by getting a bunch of people to work together.

> Can anyone invent some acronym, create their own "workgroup"?

Yes. Whether other people care that they have done so or not is another question.

> Do you need some blessings from YAML or someone else?

No.

Re: RAML – RESTful API modeling language

#47

Post by bct »

philwelch wrote: post #45
dragonwriter wrote: post #44

Earlier quoted context omitted.

> How does this miss the point of REST? Because if it didn't, the full API description language would be: api-root: Or, for a pedantically detailed version: api-root: media-types: - -

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?

https://www.ietf.org/rfc/rfc5023.txt

Re: RAML – RESTful API modeling language

#48

Post by mohsen1 »

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.

Re: RAML – RESTful API modeling language

#49

Post by sanderjd »

philwelch wrote: post #45
dragonwriter wrote: post #44

Earlier quoted context omitted.

> How does this miss the point of REST? Because if it didn't, the full API description language would be: api-root: Or, for a pedantically detailed version: api-root: media-types: - -

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?

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.

Re: RAML – RESTful API modeling language

#50

Post by SeldomSoup »

danellis wrote: post #39
SeldomSoup wrote: post #33

Earlier quoted context omitted.

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.

Oops. That's one detail I missed in all those API tutorials. Thanks.
Post reply on HN