-
Notifications
You must be signed in to change notification settings - Fork 890
Description
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 viafoo_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.