Open achimr opened 9 years ago
The link model is a very basic one. The allowed operations are up to the specific operations. Thus the curretn version just adds a some, not all possible lin options. HTTP verb PATCH - PUT should be used due to the HTTP spec only for replacing the full request, not parts of the request
DELETE, PUT, STATUS added
there is now a link returned that seems to be wrong: rel: "translation.reject" href: "http://localhost:3412/v2.0/translation/status/2b575fdc-f6af-4b9e-850d-9dc0884c6595" title: "Reject translation request 2b575fdc-f6af-4b9e-850d-9dc0884c6595" type: "application/json" verb: "PATCH"
corrected
The returned link for "translate.status" has "PATCH" as an HTTP verb. Expected: "GET" for verb
PATCH because you can change the translation status; But i have add a get methods for status too.
Currently accept/reject/confirm are documented in the spec with the HTTP verb PUT, not PATCH. There is no PATCH action documented for status.
I think we should allow a PATCH for each method; like PATCH: http://localhost:3412/v2.0/translation/confirm etc. and the body just contains true/false (as plain text) in this case. In this case we would not need a JSON body. Would make updates easier, also for the source and target...
I agree. I assume the identifier for the different values (methods) would be http://localhost:3412/v2.0/translation/{guid}/{value name} for example http://localhost:3412/v2.0/translation/2b575fdc-f6af-4b9e-850d-9dc0884c6595/professional It would be up to the server to verify if the requested change is allowed (based on process constraints - e.g. setting back the status to "initial" should maybe not be allowed; or authorization)
The question is then why we still have the accept/confirm/reject/confirm methods - the same could be achieved with setting the status value. For convenience?
As far as I understand REST and PATCH
http://localhost:3412/v2.0/translation/professional/2b575fdc-f6af-4b9e-850d-9dc0884c6595/ and body content: true
Similar to get and PUT.
This brings me to the other question/problem: As rest is quite "vague", it is not really clear if PUT is - in the strong meaning - allowed for a single attribute. As far as I saw PUT should always contain the whole request and replaces the request.
There is also an interesting aspect for POST and PUT.
PUT should always replace an object if it exists (idempotent) while POST always creates a new object. So what shall we do if the client provides two identical objects with POST? That’s was the reason why I said no GUID with POST, let do it the server.
Maybe we should replace the PUT operation on the attributes with PATCH, seems better.
Why the ID in the last part of the URL? Isn't professional a sub-attribute of the translation request?
Googling "rest put vs patch" it seems that using PATCH is very contentious and somewhat underdefined. For example: http://restful-api-design.readthedocs.org/en/latest/methods.html http://restcookbook.com/HTTP%20Methods/patch/ http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/ (offensive title)
It seems that when using JSON in PATCH one needs to use a special format to replace a resource: https://tools.ietf.org/html/draft-pbryan-json-patch-04#section-4.3
PUT seems much more straightforward and if we allow PUT on every sub-attribute we don't need to worry about having to replace the entire request (translation, comment, score) for large requests. This was the reason why we introduced PATCH in the first place.
The resource http://localhost:3412/v2.0/translation/2b575fdc-f6af-4b9e-850d-9dc0884c6595/professional is the value of professional the originally POSTed translation request and can be entirely, idempotently replaced with PUT. It is its own resource.
Regarding the POSTing of duplicate GUIDs per server we can define this as an error in the spec. GUIDs are by definition supposed to be "globally unique".
Steps to reproduce:
Issues:
status/{id}
missingPATCH
instead ofPUT
for translation.confirm|accept|cancel|reject (should bePUT
per specification)translation/{id}
is missing