A Starting Design for the Endpoints about hydrus

[chrizandr]

As applications for GSoC have started, here is a document I wrote regarding possible solutions and other specifications for the design.
Your feedback and views are highly appreciated. The document allows comments so please feel free to write your suggestions

https://docs.google.com/document/d/1YjGPwoIQh9af3OdppSBmCHaEAez8kMRy-9F9WXttQiw/edit?usp=sharing

I will write the final proposal once I get feedback from mentors on this document.

Looking forward to working with you,

Regards,

[pchampin]

<nitpicking>
creating a new object whould be either

• POST /api/cots/
  or
• PUT /api/cots/<id> (with a fresh id)
  </nitpicking>

[ddxgz]

Should it go strictly follow the REST including HATEOAS, or apply flexibly?

For creating a new object, I prefer using only POST (user specified ID could be contained in the post data body), since when doing a PUT to /objects/<id>, the target object should be already existed.

[fractos]

Just as an aside, when we were creating the Hydra API for the DLCS project (https://dlcs.info) we used the RESTful guidelines in this set of articles, which helped answer a few questions that seemed to be ambiguous about how to organise the URLs: http://restful-api-design.readthedocs.io/en/latest/intro.html

The API we have has a URL scheme like the following:

https://api.dlcs.io/customers/{customer-id}/spaces/{space-id}/images/{image-id}

The inclusion of the customers/spaces/images parts of the URL allow easily defined endpoints to POST t (and receive a Location header back), while the {xxx-id} parts are the endpoints for PUT/PATCH/DELETE. GET allowed on both, yielding a paged collection or an entity.

[pchampin]

Should it go strictly follow the REST constrains including HATEOAS, or apply flexibly?

PUT to create resources does not contradict REST nor HATEOAS.

For creating a new object, I prefer using POST (user specified ID could be contained in the post data body),

Specifying the ID in the POST body is indeed possible, but not standard, so it increases the coupling between the client and the server (note that the [Slug header from the Atom protocol]( https://tools.ietf.org/html/rfc5023#section-9.7) can still be used to *suggest* and ID, but not *specifiy* it).

since when doing a PUT to /objects/, the target object should be already existed.

Nothing in the definition of PUT imposes that.

[Mec-iS]

@pchampin I am opinionated in using PUT (:
In term of fluency POST always sounds very generic to me compared to PUT and PATCH.
But for sure we can implement both.

[pchampin]

I agree about POST being very (too?) generic, and I too like PUT for creating new resources (and PATCH for modifying them without sending the whole representation).

But my point was: if you are using PUT to create a resource, then you must address the request to the IRI of the to-be-created resource (hence the <id> in the target IRI). If you don't/can't know in advance that IRI, this can't be a PUT, and so I know no better solution than POST...

[Mec-iS]

Sorry, I forgot the id as a URL parameters for PUTs.

Yeah, that's why we should support both. If the user for his/her own sake wants to give a particular id (that is the right range for the API) he/she can do it; otherwise they can use POST and get an auto-assigned id.