REST method to Create new resource using POST

Question

1. I want to create a new resource using POST at /users { “name” : “Mr. Woods”, “age” : 29 }

2. I do not have ID in the request.

3. The server would create a new resource with an auto-generated ID (even the same data exists with a different ID which is what it is supposed to do), say 1234

4. The new resource location /users/1234 has to be returned in the response

5. Now, should I just return the new ID as return value in the response or the new ID set in the input request and return the whole entity? { “id” : 1234, “name” : “Mr. Woods”, “age” : 29 }

6. Also, when a request hits POST /users but already have an ID provided in the input, do we need to validate for this being null before creating a new one? What would be the Http response code in this case when an ID exists in the input?

Answer 1

I would use spring hateoas ( https://spring.io/projects/spring-hateoas ) and I would create an object like this:

public class User extends ResourceSupport {
    private Long id;
    private int age;
    private String name;
    //Setter and getter and eventually hashCode and equals
}

then in a controller I would a method like this:

@RequestMapping(value="/users", method={RequestMethod.POST}, produces="application/json")
public ResponseEntity<User> managePerson(@RequestBody User p)
{
  if(p.getId() != null)
  {
    //Update; in this case a 204 http status is enough and no content is required
   Return ResponseEntity.status(HttpStatus.NO_CONTENT).body(null);
  }
  else
  {
   //Save and return the saved objecty with the returned ID and set the new location
   p.add(new Link("/users/"+p.getId()));
   Return ResponseEntity.status(HttpStatus.OK).body(p);
  }

}

Answer 2

Now, should I just return the new ID as return value in the response or the new ID set in the input request and return the whole entity? { “id” : 1234, “name” : “Mr. Woods”, “age” : 29 }

A Rest POST request that is successful doesn't need necessarily to have a response body, overall if these are exactly the same data provided in the request + the created ID.
A 201 Created response that contains in the location header the URI of the created resource seems fine.

It doesn't mean that it is forbidden to set a body in the POST response, just that you should set it only if it adds some added value for the client.
For example suppose that the resource creation may change the data provided by the client (cleaning, computations, and so for...), it could make sense to set the resource in the body response.

Also, when a request hits POST /users but already have an ID provided in the input, do we need to validate for this being null before creating a new one? What would be the Http response code in this case when an ID exists in the input?

It depends on the way which you want that your Rest services behave :

• Either you decide that updating is legal with POST : in this case if the ID is null , you create the resource and if it is not null , you update the resource and if all is fine you could return 202 Accepted .
• Or you decide that updating is not legal with POST : in this other case if the ID is not null , you return a error response such as 400 Bad Request .

Answer 3

I do not have ID in the request.

You DO NOT need one. You can simply use the Db-SDK for this.

The new resource location /users/1234 has to be returned in the response

It would be better to make it hypermedia driven system HATEOS

Now, should I just return the new ID as return value in the response or the new ID set in the input request and return the whole entity? { “id” : 1234, “name” : “Mr. Woods”, “age” : 29 }

Like I said its good to return the complete hypermedia info, so that the clients can refer them without any further modification to make any restful requests

{
    "id": 1234,
    "name": "Mr.Woods",
    "age": 29,
    "address": "/1234/address",
    "some-param": "/path-to-the-resource"
}

Also, when a request hits POST /users but already have an ID provided in the input, do we need to validate for this being null before creating a new one?

Ideally, you should validate it if you are following HTTP specs. Post should always result in the creation of resource. however it's just about following specification nothing stops you if you wish to make your POST idempotent