[erlang-questions] REST server

[Loïc Hoguin]

On 03/09/2016 12:47 AM, Steve Vinoski wrote:
> I wrote it in 2008, 8 years after Roy Fielding wrote his thesis that
> defines REST. In the intervening ~16 years, REST has not changed, but
> the number of people who misuse the term and apply it incorrectly has
> grown tremendously. No web server can make your application RESTful.
> Some can help, sure, but if you want to write a system that's actually
> RESTful, as defined by Roy's thesis, then you need to read and
> understand that thesis. Even implementing Alan Dean's HTTP flowchart as
> Webmachine does isn't enough to make your application RESTful. There is
> no magic. My article simply shows how to use Yaws to help with
> organizing your code and show you how to get at the information you need
> to help make your application RESTful.

His thesis is not very interesting in the context of writing REST APIs, 
which is what most people do. Most of REST is provided by simply using 
HTTP, even if you don't use all of it, because REST is an architectural 
construct.

On top of basic HTTP the key points are:

* Stateless (the client sends everything needed to complete the request)
* Caching (boils down to defining what responses can be cached)
* Uniform interface

The latter involves the concept of resources and representations, which 
involves the content-* and accept-* headers. This is where 
Webmachine/Cowboy will help you the most.

The holy grail is HATEOAS, and that part is what most of everyone 
doesn't do today. Interaction with a server is driven by hypermedia, or 
in layman terms, client follows hyperlinks to access other resources.

This involves media types that have a concept of hyperlinks, though. For 
example, HTML has a few elements that define them and that's how 
browsers or bots navigate websites.

Any API that sends you application/json does not follow HATEOAS (even if 
they define a convention to identify links in the documentation). 
Conventions are only applicable to one site so if this API gives you a 
link to another site your client won't know what to do anymore.

Fielding has refined the REST definition a few times since his thesis, 
and in particular HATEOAS, so I'd encourage reading his most recent 
writings if you are interested in designing REST APIs.

You might also notice that while HATEOAS is useful, it kind of leaves 
you wanting more, in which case you might want to look at the works 
around the Semantic Web. But be careful not to step into madness. :-)

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang