4

So here is what the method looks like now:

POST person/personId/edit
https://api.example.com/*key*/person/*personId*/edit?FName=Blah

I want this to change the first name of person at personId to Blah.

And if I need to add a person I say:

PUT person/create
https://api.example.com/*key*/person/create

and it will add a person with a new personId.

bdukes
  • 152,002
  • 23
  • 148
  • 175
wizage
  • 304
  • 4
  • 20

2 Answers2

8

The general convention is usually:

GET    => READ
POST   => CREATE
DELETE => DELETE
PUT    => UPDATE

A difference I can see is that you are also using different URIs, what is most commonly use is a single resource URI. But, anyways that's debatable so it is a matter of how you like it.

Alexander
  • 23,432
  • 11
  • 63
  • 73
  • @wizage, after lanzz's comment, I realized you have it swap. – Alexander Jun 18 '12 at 18:10
  • From the question it seems @wizage is using POST for update and PUT for create, which differs from the answer. – lanzz Jun 18 '12 at 18:11
  • @lanzz http://stackoverflow.com/a/630475/1464439 why does it say the opposite here? – wizage Jun 18 '12 at 18:22
  • 1
    @wizage I'm only commenting on the difference between your approach and the answer's approach. _To me_, it seems more logical to create with PUT and to update with POST; [Wikipedia](http://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services), however, also uses PUT=update POST=create in the examples. – lanzz Jun 18 '12 at 18:24
  • 1
    Probably the reasoning is regarding the [idempotence of the PUT method](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods_and_web_applications), while POST is not required to be idempotent. – lanzz Jun 18 '12 at 18:26
  • @lanzz I do have it that it creates with put and updates with post. I am just documenting right now so I need to find which one is the most logical way to do this. – wizage Jun 18 '12 at 18:30
  • 1
    PUT is not an update, it is a replace, which is a strong semantic difference. I realize the age of this post, but a partial entity update should more appropriately be implemented as a PATCH. I think most things you'll see in the field use POST and PUT both as updates in different situations, but that's also why those APIs tend to be really inconsistent and confusing and not proper REST imo – Sinaesthetic May 24 '18 at 17:17
3

My interpretation of POST and PUT has always been:

POST - The server will receive an entity which it can use to perform an operation or create a resource. If the endpoint's intent is to create a resource, then POST will always create a NEW resource. In any case, each POST will be treated without regards to the state of a resource. You are simply posting information to the server for it to operate on.

Example:

  • Imagine a web service that will send a message to a user's cellphone. A POST could be used to provide the necessary information to the server which may not be appropriate for a GET. The request payload will include this information. No resources are being created on the server, so the operation returns 200 OK, indicating that the operation was completed successfully. The response may also include a body containing information from the server operation.
  • Imagine a web service that creates a ticket that is posted on a bulletin board. A POST could contain the information needed to make that post. The information is persisted on the server and returns a 201 Created (and maybe a response body which contains a user id, or a more completed object resulting from the creation). In all cases, when something is POSTed to this endpoint, a NEW ticket is created.

PUT - The server will receive an entity (with an ID, for example) with the intent of creating or replacing a resource. If the resource already exists, it will be replaced with the one within the request, otherwise a new resource will be created. In all cases, something is persisted on the server. Some way to uniquely identify the entity must be provided. In other words, the client is the one that creates the ID because it will be used if entity needs to be created. Most people I know struggle with this reality.

Example:

  • A web service receives a payload form the client containing user information. The expectation is that the user will be saved. The server will check to see if that user exists. If it does, it will update that user by replacing it (in its entirety) with the new resource provided with the request and return 200 OK or 204 No Content. If it does not exist, it will create it and return 201 Created.
Sinaesthetic
  • 11,426
  • 28
  • 107
  • 176