json-api/json-api — pull request #279 by dgeb (2014-09-26 18:09:25+00:00)
Title: Clarify updating of relationships

This PR makes the following improvements to the consistency and correctness of updating relationships:

* A `PUT` request should be allowed to the URL of a to-one relationship
* A `POST` request sent to a to-one relationship URL that already contains a relationship should fail
* A `DELETE` request sent to a to-one relationship URL that doesn't contain a relationship should fail
* A single resource ID (or an array of IDs, as previously stated) can be POSTed to a to-many relationship URL
* 404 and 409 error responses

Essentially, this establishes `PUT` as the safe way to replace a to-one relationship. `POST` and `DELETE` should only be used to verify expectations of the current value of a relationship.

In addition, I've pulled in the MUST -> SHOULD change from @harrison in #263 since it is compatible with these changes. There's also some whitespace cleanup in a separate commit.

One point of possible debate here is whether `409 Conflict` should be returned when POSTing a relationship that already exists. It seems like the most appropriate status code to me, but maybe @steveklabnik wants to weigh in :)