
An API Ontology - duvander
http://blog.steveklabnik.com/posts/2012-02-13-an-api-ontology
======
gioele
To me it seems quite an inaccurate description both of the theory and of the
status quo.

For example, the SOAP section should be "WS", web service: that is the class
of protocols like SOAP. The high-level distinction should be WS vs. RPC vs.
REST. WS is centred about the services, RPC is centred about the methods and
REST is centred around the resources. HTTP is just a transport layer, the
GET/POST style is a primitive way to implement each of these architectures. It
is the input and output data that makes a GET/POST request fit in one of these
three categories.

But what really bothers me is that, to my eyes, the author main point is that
REST is marginal and people who still seriously talk about it are akin to
those hunting unicorns. This is not explicitly said, but this is the feeling
that this article left me with.

The description of REST says

> Originally, REST was synonymous with what is now called "Hypermedia APIs."
> However, after large amounts of misunderstanding, REST advocates are
> rebranding REST to "Hypermedia APIs" and leaving REST to the RESTish folks.

I have never heard an use of "Hypermedia API" as different from "an API that
user REST". REST is an blueprint for building distributed architectures. When
you build one that follows such blueprint you end up with an "hypermedia API".

People who misunderstand REST are actually using RPC+GET/POST. These kinds of
mistakes are routinely pointed out; people will comment "the API of XYZ is not
RESTful at all! They are using _REST_ only because it is a cool term to use
nowadays". Not much different from how people misuse "multimedia", yet the
meaning of multimedia is not going to change any time soon.

When talking about REST there is spectrum to take into account: there are APIs
that fully adheres to the REST principles, other that adhere less, others that
are basically redoing SOAP or RPC yet call themselves REST because it is cool.
The same thing has happened with Agile programming. People use SVN, a code
review every now and then, write two unit tests that cover 1% of the paths and
they will says "we are doing Agile development, like all the cool kids". Yet
the meaning of what "Agile programming" is has not changed.

~~~
bsb
I never heard of "Hypermedia API" either - sounds like some REST people are
lazy, don't leverage things like content negotiation, URI de-referencing, etc
and wind up with an HTTP-RPCish monster with a REST name tag on it.

~~~
itaborai83
<http://en.wikipedia.org/wiki/HATEOAS>

~~~
bsb
HATEOAS yes, "Hypermedia API" no -- reducing the distributed state engine of
HATEOAS at the same level of RPC-style APIs doesn't adequately convey the
purpose of HATEOAS

------
shykes
_"You can tell an API is Hypermedia by providing only one API endpoint, but
which accepts requests at other endpoints that are provided by discovery."_

And then the docs provide you hardcoded URLs for each endpoint. Is there an
actual, practical use for dynamically discoverable APIs that I am missing?

------
endlessvoid94
"Ruby on Rails brought respect for HTTP into the developer world."

Excuse me?

------
NanoWar
I strongly believe that recoining the term REST to Hypermedia API won't help
preventing misunderstandings. But it sounds more like what Fielding wanted to
get across.

