
Intro to RAML 1.0 - sap1enz
http://sap1ens.com/blog/2016/12/26/intro-to-raml-1-dot-0/
======
xiaoma
I love things like RAML. It's hard to put into words how much easier it would
be for external devs if companies documented their APIs with something like
this instead of making helper libraries for a few popular languages and basing
all their docs on those helpers.

If you've got a REST API and your business relies on external devs using it,
then it's hugely valuable to document it. RAML is a tool for creating those
docs and testing an API against them in an automated way as build.

------
lobster_johnson
What I never understood about Swagger/OpenAPI and RAML was:

Why would you ever need more than one documentation viewer/playground app for
it? Why isn't there a single app, hosted somewhere for everyone to use, that I
could point to any API spec and see the docs for it and execute calls against
from the browser? If it exists, why isn't it the first thing on swagger.io,
for example?

It seems like a huge missed opportunity. The next logical step would be to let
a web site document its API URL with a meta header, so you could point the
docs browser at, say, google.com and it would just work, similar to RSS/Atom.
Then someone could write a web crawler which collected all of them and let you
look up _any_ API from the documentation browser. It doesn't take much
imagination to figure out the possibilities here. (Why isn't there a nice
native Electron app? Or maybe a Dash integration?)

In principle this does seem to be possible, since if you go to the official
Swagger demo [1], it seems you can type in the URL to any Swagger file. So why
is this a "pet store demo" and not the official Swagger browser?

[1] [http://petstore.swagger.io/](http://petstore.swagger.io/)

~~~
agentgt
While it certainly could be done it would probably be a subset of the API
because of security.

With swagger you can interactively play with the API. To do this on some other
host would require some cross origin policy setup as well probably a couple of
other things if OAuth is used.

------
stephenboyd
> Swagger and RAML are really similar, but RAML 1.0 uses its own YAML-based
> format to describe entities.

Swagger actually uses either JSON or YAML that conforms to JSON-API, but YAML
is the default in its editor web app. So they're even more similar than the
article suggests. Check it out at
[http://editor.swagger.io/](http://editor.swagger.io/)

~~~
sap1enz
I was mostly focusing on entities (schemas). Is there way in Swagger to use
something else except JSON Schema for those?

------
dozzie
So you basically invented a format that describes what functions with what
data structures are available for calling, except that the format is much more
complex than it would if the interface was exposed as a proper RPC in the
first place. Congratulations.

~~~
ci5er
Sort of, yeah. It strikes me as an inflexible IDL that had out-of-wedlock
children with an incompletely specified ASN.1. That said - they're working
with JSON/HTTP "REST-like", so there's only so much anyone could do on either
front... Anything to formalize a spec and enable some better automated tooling
would be a good thing, no?

That reminds me -- whatever happened to WS-* (and in particular WSDL and
SOAP)? Did that just wander off into the forest and die, or are people still
using that? If they are, I'd assume it's in some of the enterprise-ey
verticals?

~~~
lobster_johnson
SOAP and friends are still deeply entrenched in various "enterprise" settings
(IBM and Oracle seem to still be on that bandwagon), but it's a long time
since that stuff peaked. It's definitely legacy tech.

A few years ago I had to use some public API offered by the Norwegian
government through a private-sector partner [1]. Looks like they're still
completely SOAP/WSDL-based even today. (At the time I just needed to use a
single endpoint, so I ended up just doing everything as plain XML, instead of
generating an RPC client from WSDL; so much easier. Ugh, I'm glad I don't work
for a company that is heavily invested in that crap.)

I can't imagine anyone sane would do a greenfield project today using any of
it.

[1] [http://ws.infotorg.no/](http://ws.infotorg.no/)

~~~
tannhaeuser
It's being used in large-scale projects because it can be used in tenders. Do
you want government shell out your tax money for the latest JS fad instead?
Imagine the outcry something goes south in such a project.

I agree though that XML is overkill for describing payloads in most RPC
scenarios. XML is for describing semistructured data rather than co-inductive
data structures (arrays, records, etc.). JSON shines here precisely because it
doesn't need a schema to be useful.

However, once you have a need to communicate your API to others, or to develop
in a large project/waterfall model, schemaless doesn't cut it. JSON Schema is
doing it wrong IMHO. I think that since JSON is basically the object literal
syntax of JavaScript, an RPC mechanism could use a JavaScript subset as IDL,
in the style of "Logic Programs as Types of Logic Programs" ([1]).

Note that WSDL can describe REST-like and other HTTP-based protocols, not just
SOAP.

[1]: [http://www.informatik.uni-
ulm.de/pm/fileadmin/pm/home/fruehw...](http://www.informatik.uni-
ulm.de/pm/fileadmin/pm/home/fruehwirth/Papers/lics91p.pdf)

------
kennu
Seems a bit pointless to push a new standard when Swagger and JSON Schema
already exist and are widely supported by all kinds of documentation browsers,
API generators, validators and other tools. Competition is good of course, but
I'd look at Swagger first and see if it already satisfies all needs.

------
conceptme
I still find it a bit annoying that these docs are not in the source itself. I
personally prefer something like [http://apidocjs.com](http://apidocjs.com)
where you can write it as comments, only apidoc is still a bit limited.

~~~
sap1enz
Actually not true :) You can write your docs using "description" field, it
works in types, endpoints, query params, etc.

And the best thing - it supports markdown

------
bunkerbewohner
Skipping through the specification RAML seems to be a good deal more
"powerful" than Swagger. I have run into the limitations of Swagger and its
tooling several times already, so I'm definitely going to take a closer look
at RAML.

------
xmonader
I work for the company behind go-raml `feel free to ask any question` (we
currently make extensive use of python/go generators)

