search

adlnet / xAPI-Spec

The xAPI Specification describes communication about learner activity and experiences between technologies.
https://adlnet.gov/projects/xapi/
901 stars 405 forks source link

PUT /statements - return status 201 if statement created #1002

Open RoboSparrow opened 7 years ago

RoboSparrow commented 7 years ago

I don't know if that was already discussed before or if I am overseeing something in the specs. Section 2.1.1 states that the responsecode for a successful PUT /statements request is alway 204 No Content

Reading through https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html for PUT I stumble over:

If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response.

similar in https://tools.ietf.org/html/rfc7231#section-4.3.4

If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response. If the target resource does have a current representation and that representation is successfully modified in accordance with the state of the enclosed representation, then the origin server MUST send either a 200 (OK) or a 204 (No Content) response to indicate successful completion of the request.

This would mean that:

PUT /statements creates a statement if it doesn't exist for the given statementId

PUT /statements does not perform any action if a statement with statementId already exists

garemoko commented 7 years ago

This certainly seems helpful, however would be a breaking change and the benefits of making the change don't outweigh the cost. There will be clients who expect 204 and would break if 201 was returned.

Something to think about whenever we look at 2.0.0 though.

DavidTPate commented 7 years ago

I'm 👎 on this, as what we are doing is correct currently. Currently we return no response body and a 204 (No Content), additionally an LRS is supposed to be able to determine how it handles errors with these types of situations.

Put Statements

If the LRS receives a Statement with an id it already has a Statement for, it SHOULD verify the received Statement matches the existing one and SHOULD return 409 Conflict if they do not match. See Statement comparison requirements.