

RAML - RESTful API modeling language - DanI-S
http://raml.org/

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

~~~
tootie
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
If we want a non-RESTful (in the strict sense) solution with those particular
enterprise features, we have SOAP+WSDL.

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.

~~~
tootie
SOAP is RPC. It's fundamentally different. REST is not completely undone just
because you want validation. Without a schema or DDL, you're still validating
but you're doing it in code.

~~~
dragonwriter
> SOAP is RPC.

Yes.

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

~~~
tootie
A schema allows for declarative validation and allows it to be defined once
and once per consumer.

~~~
dragonwriter
A well-defined media-type does much the same thing and is what REST is
_centered on_.

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.

------
Terretta
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/decisi...](http://clojure-
liberator.github.io/liberator/tutorial/decision-graph.html)

Actual code: [http://clojure-liberator.github.io/liberator/tutorial/all-
to...](http://clojure-liberator.github.io/liberator/tutorial/all-
together.html)

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

------
rgbrgb
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/)

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

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

~~~
tootie
If you want strongly-typed RPC integration with generated clients then
something like Thrift, protobuf or Avro are vastly superior. Very simple and
lightweight.

~~~
jalfresi
Totally agree, these all fit the bill far better and with far less opacity
than SOAP and it's ilk.

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

~~~
zzen
Sure, API Blueprint supports JSON Schema. If you're happy to put in the
effort, nothing stops you from using JSON Schema in the blueprint and all the
tooling built on top of it.

~~~
auvrw
but that's my point: there isn't as much library support as there ought be,
even for json schema, let alone these newer domain-specific languages that
incorperate/extend json schema.

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.

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

------
ImJasonH
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...](https://code.google.com/p/google-api-go-
client/source/browse/google-api-go-generator/gen.go))

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

------
publicfig
Man, that page is hard to read.

~~~
reedlaw
Did you try mouse-hovering over paragraphs?

~~~
shaunxcode
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
Agreed, I shouldn't have to constantly move the mouse around just to read the
page.

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

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

~~~
crucialfelix
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.

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

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

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

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

------
nfoz
Really? Dark gray until mouse hover makes different paragraphs _glow_???

web devs, whyyyyy

~~~
meowface
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.

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

------
mishkinf
[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
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
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/)

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

------
tylermauthe
HATEOAS or bust.

