What should a RESTful API POST/DELETE return in the body?

Question

To follow and unfollow a person via a RESTful API, I have

• POST /person/bob/follow
• DELETE /person/bob/follow

What should these return in the body?

1. A collection of everyone you follow
2. The person you just followed / unfollowed
3. A status like { status: "ok" }
4. Nothing.

Answer 1

If you respond on errors using a HTTP server status, the status code does not say anything. If you respond with a 404 Not Found if there is no user Bob, or a 500 Internal Server Error if the database is broken, the only successful response you will ever get is OK. Users do not have to check the status code, they only have to check the HTTP status code.

I suggest you return nothing, and the fact that it is a successful response (i.e. 200 OK or 204 No Content) indicates that the operation was successful.

Answer 2

It all depends on your app/API design and the contract you are gonna define with the client/callers. But generally, in all the cases you should return status code to make your client aware of the result.

Like: respond(ResponseCode::OK, ...)

For POST: I'd return 'bob' object containing all of his followers + status code
For DELETE: I'd only return the status code.

Answer 3

Generally, for an API, I'm apologist to use the HTTP status codes instead of always OK with a code defined status. This means that you can follow the existing standards for answers, and anyone who gets an error code will know roughly what happened/what they have to do. Take a look at the wiki article http status codes for a usable reference manual.

Also, together with the error code, and because is an API we are talking about, it is useful to have a more descriptive message about the error. Something meaningful like error: "Auth token missing", or whatever standard you might come up with.

When it comes to creating resources, I generally answer back with 201 (Created) and the resource just created. Keep in mind that you might want to exclude some attributes from the resource (e.g. You're creating a user, you shouldn't return sensitive info such as the encrypted password)

Regarding the deletion of resources, generally return with either 200 (Ok) or 202 (Accepted) and no extra info.

Nevertheless, As @yek mentioned, it highly depends on the commitment with the API consumer. The most important thing is that you document the API decently and explain what should be the expectations.