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!)
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.
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.
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.
> It's fundamentally different.
It's fundamentally different than REST, sure. Its not fundamentally different than "REST" that abandons resource-oriented hypermedia.
> REST is not completely undone just because you want validation.
REST includes a validation model (indeed, its centered around one.)
It is completely undone when you toss that out and replace it with a different one.
> Without a schema or DDL, you're still validating but you're doing it in code.
With a schema or DDL, you are validating in code. It may be code in an external library or tool, but that's just a possibility with any validation model, whether its Schema-based, or Media-type-based (as in REST), or based on something else.
An API based on HTTP and schemas rather than media types for content definition/validation is more like SOAP than REST.
OTOH, an API based on resource-oriented hypermedia could incidentally use media types that are defined in terms of schemas, and still be REST.
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.
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?
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.
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.
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.
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.
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.
sometimes i think it would make just as much if not sense to define these communication protocols with a bnf grammar (for endpoints and response codes) or to use s-expressions (since json is pretty much just sugared lisp) or some other well-worn-but-adaptable format just because there are already parser generators and scheme interpreters written for every language.
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.
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.
REST needs to mature and get tooling. But we need to avoid the WSDL complexity.
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.
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/)
I found the contrast of colours on the website almost unreadable.
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.
It is, however, entirely mobile hostile.
(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")
So it sounds like true REST is supposed to solve that. How?
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.
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
web devs, whyyyyy
But making all of it dark gray (so, intended to be not-visible) by default is really silly.
1 - https://developers.helloreverb.com/swagger/
2 - http://swagger.wordnik.com/
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)?