Should I use Post or Put to edit a person in a database and which should I use to add a new person?

Question

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.

Answer 1

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.

Answer 2

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.