The original idea behind PATCH was to use a verb that could be used for many different situations:

• Updating attributes (either individual ones or all at once)
• Updating a belongs-to relationship without an inverse has-many
• Updating a has-many relationship or its inverse belongs-to relationship agnostic to whether the server stores the data via a foreign key or on the parent
• Ensuring that multiple concurrent (but separate) updates to a has-many relationship did not clobber one another
• Creating a record and linking it to a relationship at once (although the full story for this was not in the original draft)

I think the fact that PATCH is capable of handling all of these scenarios with aplomb is still a good reason to make it the default, recommended way to do updates.

That said, PATCH is a new and unfamiliar to many people, and the specific cases that it helps with aren't always apparent at first.

I'm opening this ticket to track a number of separate proposals that could avoid the need for PATCH in specific (but common) cases, and make people more comfortable with JSON API.

PUT for Attributes

#201 (Proposal: Allow updates by sending the whole record)

Updating all attributes at once is a problem that people often solve using PUT, and the reasons for PATCH don't really apply to attributes.

The PUT verb does update an entire resource all at once, so this verb is a good fit. Thinking of relationships as separate resources that happen to be linked to the record via metadata explains how this fits into HTTP.

Note: Implementations should not use PUT to update belongs-to relationships via foo_id attributes. Those kinds of attributes are not actually attributes, but instead database-specific magic attributes that happen to have the desired side effects. I wouldn't necessarily be totally opposed to extensions that tried to specify this kind of thing, but my feeling is that this kind of thing ends up being far more ad hoc and subtle than people give it credit for.

POST for Relationship Create+Update

Has-Many relationships are already represented as URLs in JSON API. This proposal would allow a new resource to be created and linked to a relationship at the same time.

It's already a very common pattern, and maps very nicely onto the concepts we already have.

PATCH Details Inside a POST or PUT

When creating a new record, it is often useful to be able to link it to other relationships at the same time. As I said above under PUT, I think that ways people tend to do this right now are very ad hoc and tend to be quite coupled to subtle and often-different details of the database schema that happens to exist on the server.

That said, people do not want to have to make multiple separate requests to create a new record and its relationships at once. For some cases, the above proposal re: POST will be enough. However, if a client wants to create a record and link it to several records at once, that strategy will not be sufficient.

Instead, I propose that we support including PATCH details for relationships inside a POST or PUT requests. We should review this proposal before 1.0 to make sure that the current PATCH configuration is not hostile to embedding for some reason, but otherwise we can move on this after 1.0 if we lack the time.