7 ms·

RAML - RESTful API modeling language

94 points by DanI-S 13y ago

grogenaut 13y ago
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.
publicfig 13y ago
Man, that page is hard to read.
- reedlaw 13y ago
  Did you try mouse-hovering over paragraphs?
  - shaunxcode 13y ago
    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.
    - tommmmmm 13y ago
      Agreed, I shouldn't have to constantly move the mouse around just to read the page.
  - Patrick_Devine 13y ago
    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.
- rjd 13y ago
  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 :/
louischatriot 13y ago
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")
rgbrgb 13y ago
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/ http://apiary.io/
rektide 13y ago
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.
taeric 13y ago
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.
- arethuza 13y ago
  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.
  - taeric 13y ago
    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.
  - tootie 13y ago
    If you want strongly-typed RPC integration with generated clients then something like Thrift, protobuf or Avro are vastly superior. Very simple and lightweight.
    - 13y ago
madisp 13y ago
Now all we are missing is a code generator that generates a stubbed site based on the raml spec...
- crucialfelix 13y ago
  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.
- stormcrowsx 13y ago
  Or just not reinvent the wheel and use SOAP. Pretty much what this thing is with a little less cruft.
deleted 13y ago
[deleted]
jalfresi 13y ago
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!)
- _pmf_ 13y ago
  > 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.
- tootie 13y ago
  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.
  - dragonwriter 13y ago
zzen 13y ago
(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.
- auvrw 13y ago
  > 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> 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.
  - usarid 13y ago
    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).
    - usarid 13y ago
      Regarding tooling.. check out the video that just went up on http://raml.org http://raml.org (and on Youtube: http://youtu.be/5o_nExedezw http://youtu.be/5o_nExedezw)
Terretta 13y ago
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/decision-graph.html http://clojure-liberator.github.io/liberator/tutorial/decisi... Actual code: http://clojure-liberator.github.io/liberator/tutorial/all-together.html http://clojure-liberator.github.io/liberator/tutorial/all-to... Progenitor = Erlang Webmachine: https://github.com/basho/webmachine/wiki/Overview 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.
- usarid 13y ago
  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!
ImJasonH 13y ago
This seems similar to Google's Discovery Service (https://developers.google.com/discovery/ 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 https://developers.google.com/apis-explorer) and code generators (e.g., https://code.google.com/p/google-api-go-client/source/browse/google-api-go-generator/gen.go 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/ https://developers.google.com/appengine/docs/java/endpoints/)
nickporter 13y ago
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 https://thrift.apache.org
jamespitts 13y ago
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.
- zzen 13y ago
  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.
  - jamespitts 13y ago
    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.
  - be-prepared 13y ago
    Good luck avoiding complexity when you hit P2P security, transactions, etc.
mishkinf 13y ago
https://github.com/mishkinf/apiknow https://github.com/mishkinf/apiknow is another project to help build out an api documentation and Test Drive it
- inerte 13y ago
  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/ https://developers.helloreverb.com/swagger/ 2 - http://swagger.wordnik.com/ http://swagger.wordnik.com/
  - jjsz 13y ago
    How does Swagger compare with Scrooge (Twitter's Scala / Apache Thrift code generator)[0]? [0] http://twitter.github.io/scrooge/ http://twitter.github.io/scrooge/
mcguire 13y ago
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?
crazychrome 13y ago
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)?
viblo 13y ago
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.
- usarid 13y ago
  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.
nfoz 13y ago
Really? Dark gray until mouse hover makes different paragraphs glow??? web devs, whyyyyy
- meowface 13y ago
  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.
tylermauthe 13y ago
HATEOAS or bust.
phamilton 13y ago
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?

94 points by DanI-S 13y ago

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.

publicfig 13y ago

Man, that page is hard to read.

reedlaw 13y ago
Did you try mouse-hovering over paragraphs?
- shaunxcode 13y ago
  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.
  - tommmmmm 13y ago
    Agreed, I shouldn't have to constantly move the mouse around just to read the page.
- Patrick_Devine 13y ago
  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.
rjd 13y ago
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 :/

louischatriot 13y ago

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

rgbrgb 13y ago

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/ http://apiary.io/

rektide 13y ago

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.

taeric 13y ago

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.

arethuza 13y ago
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.
- taeric 13y ago
  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.
- tootie 13y ago
  If you want strongly-typed RPC integration with generated clients then something like Thrift, protobuf or Avro are vastly superior. Very simple and lightweight.
  - 13y ago

madisp 13y ago

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

crucialfelix 13y ago
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.
stormcrowsx 13y ago
Or just not reinvent the wheel and use SOAP. Pretty much what this thing is with a little less cruft.

deleted 13y ago

[deleted]

jalfresi 13y ago

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

_pmf_ 13y ago
> 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.
tootie 13y ago
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.
- dragonwriter 13y ago

zzen 13y ago

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

auvrw 13y ago
> 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> 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.
- usarid 13y ago
  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).
  - usarid 13y ago
    Regarding tooling.. check out the video that just went up on http://raml.org http://raml.org (and on Youtube: http://youtu.be/5o_nExedezw http://youtu.be/5o_nExedezw)

Terretta 13y ago

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/decision-graph.html http://clojure-liberator.github.io/liberator/tutorial/decisi... Actual code: http://clojure-liberator.github.io/liberator/tutorial/all-together.html http://clojure-liberator.github.io/liberator/tutorial/all-to... Progenitor = Erlang Webmachine: https://github.com/basho/webmachine/wiki/Overview 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.

usarid 13y ago
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!

ImJasonH 13y ago

This seems similar to Google's Discovery Service (https://developers.google.com/discovery/ 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 https://developers.google.com/apis-explorer) and code generators (e.g., https://code.google.com/p/google-api-go-client/source/browse/google-api-go-generator/gen.go 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/ https://developers.google.com/appengine/docs/java/endpoints/)

nickporter 13y ago

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 https://thrift.apache.org

jamespitts 13y ago

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.

zzen 13y ago
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.
- jamespitts 13y ago
  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.
- be-prepared 13y ago
  Good luck avoiding complexity when you hit P2P security, transactions, etc.

mishkinf 13y ago

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

inerte 13y ago
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/ https://developers.helloreverb.com/swagger/ 2 - http://swagger.wordnik.com/ http://swagger.wordnik.com/
- jjsz 13y ago
  How does Swagger compare with Scrooge (Twitter's Scala / Apache Thrift code generator)[0]? [0] http://twitter.github.io/scrooge/ http://twitter.github.io/scrooge/

mcguire 13y ago

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?

crazychrome 13y ago

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

viblo 13y ago

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.

usarid 13y ago
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.

nfoz 13y ago

Really? Dark gray until mouse hover makes different paragraphs glow??? web devs, whyyyyy

meowface 13y ago
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.

tylermauthe 13y ago

HATEOAS or bust.

phamilton 13y ago

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?