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!)
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.
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.
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.
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!
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/
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?
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.
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.
(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.
> 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> 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.
(disclaimer, I'm from the RAML workgroup -- nice to see you here, Jakub!)
As you know, we carefully considered swagger and blueprint, before embarking on the RAML path. There's a bunch of us who are strong believers in very human-readable API specs, though we also strongly believe in clean API specs that reveal the structure of the API and encourage consistency and reuse -- and we just didn't find that in existing DSLs.
We're actually not finding any issues embedding markdown documentation in RAML at just those points in the spec that need documentation, while letting the spec itself do the talking when more documentation would just be repetitive. That way the structure of the API is manifest.
We also find the spec to be much DRYer in RAML than other ways; less repetitive reading means quicker and better grokking of the API.
I think the point about syntax highlighting in generic editors is debatable, but that's fine -- as you say, we have two different approaches and we'll keep each other on our toes, to the benefit of the community. Apiary's dedication to user experience is an inspiration to us. And just in case, my invitation to you to consider collaborating with us and the other workgroup members on RAML remains very much open.
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.
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 :/
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.
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?
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.
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.
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.
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)?
[+] [-] jalfresi|12 years ago|reply
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!)
[+] [-] smizell|12 years ago|reply
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.
[+] [-] _pmf_|12 years ago|reply
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|12 years ago|reply
[+] [-] Terretta|12 years ago|reply
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.
[+] [-] usarid|12 years ago|reply
[+] [-] rgbrgb|12 years ago|reply
[+] [-] mcguire|12 years ago|reply
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?
[+] [-] taeric|12 years ago|reply
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|12 years ago|reply
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.
[+] [-] zzen|12 years ago|reply
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|12 years ago|reply
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> 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|12 years ago|reply
As you know, we carefully considered swagger and blueprint, before embarking on the RAML path. There's a bunch of us who are strong believers in very human-readable API specs, though we also strongly believe in clean API specs that reveal the structure of the API and encourage consistency and reuse -- and we just didn't find that in existing DSLs.
We're actually not finding any issues embedding markdown documentation in RAML at just those points in the spec that need documentation, while letting the spec itself do the talking when more documentation would just be repetitive. That way the structure of the API is manifest.
We also find the spec to be much DRYer in RAML than other ways; less repetitive reading means quicker and better grokking of the API.
I think the point about syntax highlighting in generic editors is debatable, but that's fine -- as you say, we have two different approaches and we'll keep each other on our toes, to the benefit of the community. Apiary's dedication to user experience is an inspiration to us. And just in case, my invitation to you to consider collaborating with us and the other workgroup members on RAML remains very much open.
[+] [-] jamespitts|12 years ago|reply
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|12 years ago|reply
REST needs to mature and get tooling. But we need to avoid the WSDL complexity.
[+] [-] ImJasonH|12 years ago|reply
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/)
[+] [-] publicfig|12 years ago|reply
[+] [-] rjd|12 years ago|reply
[+] [-] reedlaw|12 years ago|reply
[+] [-] madisp|12 years ago|reply
[+] [-] crucialfelix|12 years ago|reply
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|12 years ago|reply
[+] [-] rektide|12 years ago|reply
It is, however, entirely mobile hostile.
[+] [-] louischatriot|12 years ago|reply
(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")
[+] [-] phamilton|12 years ago|reply
So it sounds like true REST is supposed to solve that. How?
[+] [-] grogenaut|12 years ago|reply
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.
[+] [-] nickporter|12 years ago|reply
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
[+] [-] viblo|12 years ago|reply
[+] [-] usarid|12 years ago|reply
[+] [-] nfoz|12 years ago|reply
web devs, whyyyyy
[+] [-] meowface|12 years ago|reply
But making all of it dark gray (so, intended to be not-visible) by default is really silly.
[+] [-] mishkinf|12 years ago|reply
[+] [-] inerte|12 years ago|reply
1 - https://developers.helloreverb.com/swagger/ 2 - http://swagger.wordnik.com/
[+] [-] crazychrome|12 years ago|reply
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)?
[+] [-] unknown|12 years ago|reply
[deleted]