CODEWITHSUNDEEP
jsonrest
jay_t
jay_t

Reputation: 3793

Advice required on correct RESTful response format for the "deepest" resource item

I have a "conceptual" question about designing a RESTful API which returns and accepts data in JSON format.

Consider following requests and responses:

GET http://host/records/12345

{ "id":"12345", "address":{"street":"main street","number":5,"city":"springfield"}}

GET http://host/records/12345/address

{"street":"main street","number":5,"city":"springfield"}

GET http://host/records/12345/address/city

{"city":"springfield"}

OR

springfield (=not valid json)

I realize that the second answer isn't a valid JSON response so I presume the latter is the correct answer to my question. However it looks redundant to me to respond in the form of a key/value since the requester already knew the "key" during the request.

Same counts for updates:

When I want to update the city of my 12345 record with another value what would be more correct to submit:

PUT http://host/records/12345/address/city

{"city":"paris"}  <- content of body when submitting

OR

paris <- content of body when submitting (=not valid json)

The reason I'm asking is because one would already have enough by doing

PUT http://host/records/12345/address

{"city":"paris"}   <- content of body when submitting

What would be considered to be most appropriate approach to this?

Thanks,

Jay

Upvotes: 2

Views: 116

Answers (2)

Darrel Miller
Darrel Miller

Reputation: 142044

If you really want to do this "micro-PUT" style of updating then consider just sending the body using the text/plain media type. One of the beauties of using HTTP is that you can freely mix and match media types to use what is the most appropriate.

PUT http://host/records/12345/address/city
Content-Type: text/plain
Content-Length: 5

paris

=> 
200 OK

Be warned though, HTTP is optimized for working with large grain resources. If you see your users wanting to do these kind of small updates frequently then maybe you need to reconsider the approach.

Upvotes: 1

Kevin Junghans
Kevin Junghans

Reputation: 17540

REST API's generally work on resources, which loosely translate to objects or tables in a database. Your first example of a GET does not indicate that you are trying to get a resource of type "address". What if you want to add additional resources to your API, for example "companies", then this would not be clear. And there should be a way to get a list of all of the addresses. So to get all of the addresses the API call would look like

GET http://host/records/address

[{"id":"12345", "street":"main street","number":5,"city":"springfield"},
{"id":"12346", "street":"foo street","number":1,"city":"alexandria"}]

To get a specific address it would look like

GET http://host/records/address/12345

{"id":"12345", "street":"main street","number":5,"city":"springfield"}

That id is part of the address object and I do not see any need to break it out into a parent object as in your example. You then use that id to let your web service know what needs to be updated. So your update would look like this.

PUT http://host/records/address

{"id":"12345", "street":"main street","number":5,"city":"paris"}

Usually the client would send the whole object over and not just the fields to update.

Upvotes: 2

Related Questions