Handling RESTful representation structure difference between POST and GET

Question

I'm designing a REST API and despite trawling a number of best practice guides I can't find much relating to the best practice of handling the disparity between representation structure needed for a POST vs the same representation structure returned from a GET.

GET for a dummy user representation might look like this:

{
    "id": 1234,
    "created": "2012-04-23T18:25:43.511Z",
    "username": "[email protected]",
    "name": "John Doe"
}

However, POST for the same dummy user representation cannot specify certain properties (namely the id and created):

{
    "username": "[email protected]",
    "name": "John Doe"
}

Obviously this is an overly simplified example but given that the user cannot specify certain fields (and it might not always be obvious which ones are pertinent to the applied method) is it best practice to create separate representations for each or to expect the most complete version and handle the data disparity transparently on the server?

Despite the apparent ease of having a single representation and handling the disparity server side I am worried that this would be a bad experience for a user if it wasn't clear which values can be specified (or altered using PUT for example). If the tendency is to create separate representations is there a naming convention to apply to the representation definition?

e.g. i_user for incoming user and o_user for outgoing user. Or user_full and user_min or user and .user etc.

Update: My overly simplified example perhaps didn't properly illustrate the issue. Imagine a representation that has 50 properties (for example a server representation with all its monitoring attributes - cpu, ram, temp, storage_drive_a, storage_drive_b, file_permission etc.) Of these 50 properties, 30 are read only properties and 20 of these are values that can be set.

Answer 1

First of all, the final semantics of the POST method are determined by the targeted resource, not by the HTTP protocol, as with the other methods, so your POST method can do anything you want, as long as you document it properly, and you are not replicating functionality already standardized by other methods.

So, in short, there's nothing wrong with having a different representation for POST and GET method.

However, asking for a best-practice in this case is pointless, because what defines the representation format is the media-type being used, not the method, but most of the so-called REST APIs around the internet use generic media-types for everything and clients rely on URI semantics to know which resource they are dealing with, which is not RESTful at all. Basically, you are asking for the best-practice for a problem that doesn't really exist in REST when things are done properly.

So, to answer your question, you can have different representations with different media-types -- like your complete user representation might have a media-type application/vnd.mycompany.user.full.v1+json, and a simplified user representation might have a media-type application/vnd.mycompany.user.min.v1+json -- or you can have a single representation like application/vnd.mycompany.user.v1+json and your documentation for this media-type might detail how some properties might exist or not, or might have default values if not provided. Your POST method will require one media-type to work, and will respond with 415 Unsupported Media Type if clients send anything else in the Content-Type header. In the same way, a client may choose the representation it wants with the Accept header.

As you can see, what you are asking isn't a problem when you are really doing REST, and not merely using it as a buzzword for an HTTP API.