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.
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?
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.
Yeah - combine with a SaaS for hosting your swagger file, automated monitoring/testing of your endpoint and a directory of apis for use or just cloning the interface
> 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/
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.
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?
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.
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.
Sure people are still using it. Nothing ever dies in the technology world. People are still using COBOL, Fortran, MVS, OS/400, AIX, Irix, etc. too. But it's clearly not "hip" anymore, which means that any comment on the matter here on HN will invariably be negative. Well, almost any.
There's this weird dichotomy in tech: we're heavily fad-driven and obsessed with the latest, newest, cool, hip "stuff" on one hand, but on the other hand, no old tech ever really dies. Or at least, it take a LONG time to completely die.
So basically, any tech more than about 4 years old is in this weird zombie state where it isn't dead, but isn't "what the cool kids use" anymore.
This. For the last month I've been working on a big enterprise Flash flex application that talks to a PHP backend.
It seems that flex mxml is a good idea, but once apple decided to kill flash, the developer community jumped ship. Thankfully adobe gave flex to apache, and a small community lives on.
The interesting opportunity seems to be that there remain quite a few good consulting opportunities for flex devs.
The employers are getting a little anxious about finding devs and many are willing to work with you no matter your time zone :)
There seems to be value here in describing APIs to external developers and giving them a playground for it. Well, there is value there because some large companies do that as their product.
There isn't a great solution for writing API documentation, still, although something like this probably helps a good bit. Even better if the real implementation is validated by the doc
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.
I still find it a bit annoying that these docs are not in the source itself. I personally prefer something like http://apidocjs.com where you can write it as comments, only apidoc is still a bit limited.
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.
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.