No way to do UPSERT using PUT

[qrilka]

According to HTTP spec it is possible to create new resource by PUTting to its desired URI - http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 :

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

And it's not possible with flask-restless as it requires table row to be already present:

# create a SQLAlchemy Query which has exactly the specified row
query = query_by_primary_key(self.session, self.model, instid)
if query.count() == 0:
    abort(404)

[jfinkels]

The relevant part of the specification is as follows, with emphasis added.

If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

So the server can allow this behavior, but it is not required. That being said, I might be able to be convinced that this is a useful feature. Is there any real-world situation in which being able to specify the primary key (for example, PUT /person/1 ... as opposed to PUT /person ...) is useful?

[qrilka]

The situation was stated in issue title - to do an UPSERT. With current flask-restless API I don't see any way to do it without either running multiple REST calls (in my prototype for which I used flask-restless I just run POST and then PUT which give update after insert with the same values) or just switching to ordinary flask handlers.
BTW primary keys are not always the case - in my prototype I do host discovery and use MAC address as a primary key also it is not very rare to see UUID used for such purposes.

[jfinkels]

Hmm, this seems like it might be difficult to implement given the current code. I'm still a little confused about what you are looking for, though. Can you give me an example of an HTTP request that should perform an upsert, and describe the state of the model before and after the request?

[qrilka]

Actually I have finished that prototype and dont' have such tasks at the moment.
But the example was like the following:
I was doing host discovery and used flask to store discovered machine data and MAC was used as a primary key for that table (actually MAC for IPMI interface). So using PUT on /api/host/ I wanted to idemponently UPSERT host data into the database. As it is not possible right now in flask-restless I have used 2 calls: POST + PUT

[jfinkels]

So what you want is this:

If the database is initially empty, a request

PUT /api/person/1 HTTP/1.1
Host: example.com

{"name": "Foo"}

should create a new row in the table in which field 'id' (the primary key, say) has value 1 and field 'name' has value "Foo".

Then subsequent requests

PUT /api/person/1 HTTP/1.1
Host: example.com

{"name": "Bar"}

should update the existing row of the table so that it has ID 1 but now has name "Bar"?

[qrilka]

Looks like it was something like that, not sure that it's very frequent usecase but sometimes it could be useful

[davismj]

A PUT typically has an upsert behavior and does NOT specify the primary key in the URI.

Should create a new instance of widget in the database:
PUT: /api/widget
Request body: { attribute: 'something' }

Should update an existing instance of widget in the database, if it exists, or create a new one if no resource was found with that primary key:
PUT: /api/widget
Request body: { id: 1, attribute: 'something else' }

[jfinkels]

@davismj Thanks for the clarification. So in the first case, the PUT request is really acting like a POST, and in the second the PUT request is acting like a PATCH (that is, a request to PUT /api/widget with body {"id": 1, "foo": "bar"} is really like a request to PATCH /api/widget/1 with body {"foo": "bar"}), except if the ID doesn't exist, then it acts like a POST but with a specified ID?

[davismj]

yes, although, put api/widget/1 acts like a post optionally, put api/widget should always act like a post

[jfinkels]

This is no longer relevant, since Flask-Restless now follows the JSON API specification, which only allows POST and PATCH requests.

[qrilka]

@jfinkels if so, shouldn't it appear on http://jsonapi.org/implementations/ ?

[jfinkels]

Technically, the code implementing JSON API is not released yet. I'd like to release at least a beta version before submitting the project to that list.

[jfinkels]

In any case, I just created issue #489 for tracking that issue.