Question

I’m using Web Api and have a scenario where clients are sending a heartbeat notification every n seconds. There is a heartbeat object which is sent in a POST rather than a PUT, because as I see it they are creating a new heartbeat rather than updating an existing heartbeat.

Additionally, the clients have a requirement that calls for them to retrieve all of the other currently online clients and the number of unread messages that individual client has. It seems to me that I have two options:

1. Perform the POST followed by a GET, which to me seems cleaner from a pure REST standpoint. I am doing a creation and a retrieval and I think the SOLID principles would prefer to split them accordingly. However, this approach means two round trips.
2. Have the POST return an object which contains the same information that the GET would otherwise have done. This consolidates everything into a single request, but I’m concerned that this approach would be considered ill-advised. It’s not a pure POST.

Option #2 stubbed out looks like this:

public HeartbeatEcho Post(Heartbeat heartbeat)
    {
    }

HeartbeatEcho is a class which contains properties for the other online clients and the number of unread messages.

Web Api certainly supports option #2, but just because I can do something doesn’t mean I should. Is option #2 an abomination, premature optimization, or pragmatism?

Answer 1

The option 2 is not an abomination at all. A POST request creates a new resource, but it’s quite common that the resource itself is returned to the caller. For example, if your resources are items in a database (e.g., a Person), the POST request would send the required members for the INSERT operation (e.g., name, age, address), and the response would contain a Person object which in addition to the parameters passed as input it would also have an identifier (the DB primary key) which can be used to uniquely identify the object.

Notice that it’s also perfectly valid for the POST request only return the id of the newly created resource, but that’s a choice you have, depending on the requirements of the client.

public HttpResponseMessage Post(Person p)
{
    var id = InsertPersonInDBAndReturnId(p);
    p.Id = id;
    var result = this.Request.CreateResponse(HttpStatusCode.Created, p);
    result.Headers.Location = new Uri("the location for the newly created resource");
    return result;
}