[99s-extend] Full example of cowboy_rest?

[Paulo F. Oliveira]

Hello, Stéphane.

On 24 August 2014 10:54, Stéphane Wirtel <stephane at wirtel.be> wrote:
>
> Hi all,
>
> Do you have a concrete example of cowboy_rest ? with POST, GET, HEAD, PUT and DELETE ?

AFAIK, from the official examples, the correct answer is "no", there
is no "complete" example (does it even make sense to have one?).

On the other hand, I've been using Cowboy for a couple of months now,
and find these docs (REST flowcharts -
http://ninenines.eu/docs/en/cowboy/1.0/guide/rest_flowcharts/) to be
very useful, and they might also help you. You should find the time to
read the complete REST guide/manual as a lot of useful information can
be found there and a very nice effort was put into not wasting words
and going straight to the point.

...

> What are the best practices?

For what specifically?

> The examples in the repository of cowboy don't cover all the possibilities of a simple rest api with these verbs.

That is a fact. I, for one, tend to have a _template_ source code file
from where I get the functions that I need (only not to have to write
2/3 lines of code every time), and that I "chain" looking at the
flowcharts. [I also have a lib for JSON parsing and validating, query
string validation, etc...] This might not always be very easy (to
"chain" it all together, but it shouldn't be that hard either"), but
my approach is usually "OK, so I want a route to have GET, PUT and
DELETE... what are the related methods that I'll most probably
require? resource_exists (serves all methods), is_conflict (serves
PUT), delete_resource (serves DELETE), delete_completed (serves
DELETE)" and then I think about replying with a body or not (in the
case of GET there will almost always be a body, in the case of PUT
your method call might result in a 204 and in the case of DELETE there
may or not be a body). I then code the methods, test the API, checking
that the codes I get make sense (404, 200, 409, 204, 202, ...
depending on the conditions I want set) and then slightly document
this for the users of the API (if the API is complicated and requires
a lot of documentation there might be something wrong with it). For
documentation purposes you can either go with a "[VERB] route
accepts...?..., serves...?..., and the result codes are...?..." simple
doc or something more elaborate like
https://helloreverb.com/developers/swagger.

Hope it helps.

- Paulo F. Oliveira

>
> Thanks in advance,
>
> Stephane
>
> --
> Stéphane Wirtel - http://wirtel.be - @matrixise
> _______________________________________________
> Extend mailing list
> Extend at lists.ninenines.eu
> https://lists.ninenines.eu/listinfo/extend