REST API – Should a REST Interface Include the Query ID in Responses?

jsonrestweb-api

I am currently working an Android app that receives most of the displayed data from a REST interface.

First, I request the information for a company the request includes a list of store IDs. With each ID I can then request the details for this store.

As part of my app I can update the store opening hours and send them back to the server. For that, I obviously need the store ID to tell the server which store to update.

Now, my question: The JSON object returned by {SERVER}/StoreDetails/{ID} does not include the the store ID. So I need to first fetch the JSON, parse it, and then manually add the store ID to the object – which I feel needlessly complicates my logic, as well as my model objects which now either need a setter of some kind of copy/update constructor when they could otherwise be totally immutable…

Would it be/have been reasonable to include the store ID in the returned JSON object or is that considered redundant and a bad practice?

Best Answer

Sounds perfectly reasonable to me to add the store ID into the payload - as you say, the payload is then more "standalone", and should not need modified after being parsed. Messing with the object to inject a field that you could trivially include when building the response feels wrong to me.

Related Solutions

Rest – Proper response for a REST insert – full new record, or just the record id value

Well, in a REST interface, following HTTP where ever possible, I would return a 201 and an URI in the Location header field to the newly created Resource. Here is what Status Code Definitions says:

10.2.2 201 Created

The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead.

If something went wrong, I would argue you shouldn't return -1 as others have said, but simply a Client or Server Error Code (4xx or 5xx). For example, if a user is not allowed to create some new resource, you would simply return a "401 Unauthorized", nothing more and nothing less.

REST API Design – Should API Return Nested JSON Objects?

Another alternative (using HATEOAS). This is simple, mostly in practice you add a links tag in the json depending on your use of HATEOAS.

http://api.example.com/games/1:

{
  "id": 1,
  "title": "Game A",
  "publisher": "Publisher ABC",
  "developer": "Developer DEF",
  "releaseDate": "2015-01-01",
  "platforms": [
    {"_self": "http://api.example.com/games/1/platforms/53", "name": "Playstation"},
    {"_self": "http://api.example.com/games/1/platforms/34", "name": "Xbox"},
  ]
}

http://api.example.com/games/1/platforms/34:

{
  "id": 34,
  "title": "Xbox",
  "publisher": "Microsoft",
  "releaseDate": "2015-01-01",
  "testReport": "http://api.example.com/games/1/platforms/34/reports/84848.pdf",
  "forms": [
    {"type": "edit", "fields: [] },
  ]
}

You can off course embed all data in all listing but that will likely be way too much data. This way you can embed the required data and then load more if you really want to work with it.

The technical implementation can contain caching. You can cache the platforms links and names in the game object and send it instantly without having to load the platforms api at all. Then when required you can load it.

You see for example that I added some form information. I did that to show you there can be much more information in a detailed json object than you would even want to load in the listing of games.

Best Answer

Related Solutions

Rest – Proper response for a REST insert – full new record, or just the record id value

REST API Design – Should API Return Nested JSON Objects?

Related Topic