Restful webservices....Put or post for a updating

Question

I have a restful webservice for which iam writing a new method call. The purpose of the new method call is to revoke the status of a person to "NO".

All that I have to send in the request is a Person_Id for which the status needs to be changed to "NO".

Should I be using PUT or POST to do this?

If I use put, can I just send the person_id as a path parameter and not use any xml at all. (like : http://serverName/PersonServices/Person/123456) and in the service layer, i have my code like this.

    @PUT
    @Path("/Person/{person_Id}")
    @Consumes("application/xml")
    @Produces("application/xml")
    public JAXBElement<GetUsageTokenType> updateLicenseStatus(
            @PathParam("person_Id") final Long personId) {

            //code to change the status
     }

Or should I be using POST to do this... Am I right in saying that if I use POST, I need to send xml format?

Here is the W3C HTTP RFC for POST & PUT: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5 — Jesse Webb, Oct 03 '12 at 14:31
Here is a similar question about PUT vs. POST in REST: http://stackoverflow.com/q/630453/346561 — Jesse Webb, Oct 03 '12 at 14:34

score 3 · Accepted Answer · edited May 23 '17 at 11:53

3

If you look at Which HTTP methods match up to which CRUD methods? there shows the mapping

Create = PUT with a new URI
         POST to a base URI returning a newly created URI  
Read   = GET  
Update = PUT with an existing URI  
Delete = DELETE

If you read the HTTP RFC for each verb's definition you can see why...

In response to:

can I just send the person_id as a path parameter and not use any xml at all

then ideally your URL

http://serverName/PersonServices/Person/123456

should probably be

http://serverName/PersonServices/RevokePerson/123456

This will help for maintainability if you don't want to pass any XML/JSON/etc but whether human-readable URLs are a feature of RESTful services is a llloooonnnggg-running argument

As alluded to in the comments RESTful APIs should focus on content and not actions. See: Why does including an action verb in the URI in a REST implementation violate the protocol? for example.

So you'd pass a person to a URL and based on the HTTP verb the relevant CRUD action is taken. If you want to pass just an ID then you're going to have to guess what update to take when you PUT to the ID... unless you know that there's never going to be any other update ever ever ever.

edited May 23 '17 at 11:53

Community

1
1

answered Oct 03 '12 at 13:58

Paul D'Ambra

7,629
3
51
96

1

I think RESTful APIs should not include action verbs in their URLs. The inclusion of RevokePerson in your suggested URL makes this not resource-based. – Jesse Webb Oct 03 '12 at 14:26
Like I say it's a long-running argument. How do you carry out two different updates against person if you only want to specify an id in the URL? I guess really you should PUT a serialized Person and that would update (in this instance by revoking a license) the Person at the other end. I suppose I wasn't clear about responding to this: "can I just send the person_id as a path parameter and not use any xml at all" – Paul D'Ambra Oct 03 '12 at 14:52
I agree; the topic still has lots of active discussion. I have tried using action verbs in URLs and it led to many (100s) of different URLs for modifying the same resources in various ways. It turned out to be a bad idea, so I was just trying to steer others away from falling into the same hole. It is really just my opinion though and what failed for me might be the right thing to do for someone else, hence why I didn't down-vote. ;) – Jesse Webb Oct 03 '12 at 16:10

score 0 · Answer 2 · answered Oct 03 '12 at 13:54

0

It depends on how you implement your server, but following proper REST principles, you'll want to use PUT.

answered Oct 03 '12 at 13:54

Jordan Denison

2,649
14
14

Jesse Webb · Answer 3 · 2012-10-03T14:35:52.887

I would suggest that you POST to the URL:

http://serverName/PersonServices/Person/123456

You should not POST an empty body though, your body should contain the fields you would like to update, in standard POST body parameter syntax.

E.g. status=NO

For individual (or multiple) field updates, I think this is the best way. For example, if you needed to update a couple fields in your request, you could use...

firstName=Jesse&status=YES

This way the URL maintains the fact that they correspond to resources (as opposed to an action like if you you included a RevokePerson or similar path argument). This provides the most flexibility with minimal pollution of your API by avoiding a bunch of different URL endpoints for every operation you would like to do.

Restful webservices....Put or post for a updating

3 Answers3