1

I am currently learning REST practices with the help of the excellent book of Richardson "RESTful Web Services". I would like to design a REST API that follows the maturity model of Richardson, especially the level 3 called HATEOAS which seems to be the most complicate to handle.

Firstly, I don't really understand the different meaning between a link and a form ?(regarding the hypermedia, I know the HTML explanation..). Is it simply a matter of "link is for GET method" and "form is for GET/POST/PUT methods" ?

EDIT1: I got the point: forms can be application forms for constructing a URI and use a GET method or can be resource forms for PUT/POST methods (more or less what i asked). Correct me if I'm wrong, links are supposed to be use carefully by the client with the OPTIONS method to know how it can be use.

As I want to be compliant to HATEOAS, I need to choose an hypermedia format... and I know that it exists several of format such as Siren, HAL, Collection+JSON, JSON-LD, Hydra, etc... But well, I don't know which one to use ?

In the Richardson's book, he uses xHTML which has one main good point: testing your API with a browser. But xHTML seems to be heavy. I would probably prefer something more lightweight but the recent hypermedia format (Siren, HAL, ...) are probably too recent and complex to test without a programmable client.

Poke
  • 115
  • 8
  • Can you present one clear question? It isn't clear what you're asking. – Pedro Werneck Nov 03 '14 at 23:29
  • It's all about hypermedia: difference between 2 concepts (links and forms) and which hypermedia format I should use. Cannot be more clear. – Poke Nov 04 '14 at 08:06
  • 1
    HAL & Siren both have very nice browsers. http://haltalk.herokuapp.com/explorer/browser.html#/ & http://siren-browser.herokuapp.com/ – Chris DaMour Nov 06 '14 at 18:09

1 Answers1

2

I would definitely recommend you to give it a try to the siren format for your API. As they correctly mentioned in one of the comments in has a nice browser...but that one is poorly supported (you can see it in their github repository).

So you should use this one which was based on the first mentioned but it has some extras like: nice error handling & supports actions for nested entities (among others)

Regarding the difference between link and forms... well my 5 cents are that you use links for GET requests that require no input params from your client and actions (talking in siren format) for POST, PUT, PATCH, GET actions that do require sending some params to the server.

Now, you could say: "But I can have this link http://testsite.com/api/v1/users?param1=value1" and still be passing params. You're correct, BUT!, how would your client now that it can pass this or that param.

That's why you have actions with a key called 'fields' where you describe the fields you're willing to accept.

Enjoy hypermedia APIs!

Daniel
  • 2,989
  • 2
  • 25
  • 26
  • I was wondering if Siren will reach a stable version ? Because on an other hand, I saw that Hydra is pushing up by the W3C... but it seems to be too recent ? – Poke Nov 18 '14 at 10:05
  • 1
    Sorry to comment again. Just find one helpful link that compares CollectionsJSON/HAL/Siren: https://github.com/kevinswiber/siren/issues/15 ; Siren seems to be fine in my case! – Poke Nov 18 '14 at 12:20