How should I deal with object hierarchies in a RESTful API?

Question

I am currently designing the API for an existing PHP application, and to this end am investigating REST as a sensible architectural approach.

I believe I have a reas

Answer 1

Here's my conclusions from many hours searching and with input from the responders here:

Where I have an object that is effectively a multi-part object, I need to treat that as a single resource. Thus if I GET the object, all the sub-ordinates should be present. This is required in order that the resource is cacheable. If I part load the object (and provide an ETag stamp) then other requestors may receive a partial object when they expected a full one. Conclude - objects should be fully populated if they are being made available as resources.

Associated object relationships should be made available as links to other (primary) resources. In this way the objects are discoverable by traversing the API.

Also, the object hierarchy that made sense for main application site may appear not be what you need to act in RESTful manner, but is more likely revealing problems with the existing hierarchy. Having said this the API may require more specialised use cases than had been previously envisaged, and specialised resources may be required.

Hope that helps someone

Answer 2

There's no reason not to combine these.

• api.example.com/user/{user_id} – return a user representation
• api.example.com/channel/{channel_id} – return a channel representation
• api.example.com/user/{user_id}/channels – return a list of channel representations
• api.example.com/user/{user_id}/channel_list – return a list of channel ids (or links to their full representations, using the above links)

When in doubt, think about how you would display the data to a human user without "API" concerns: a user wants both index pages ({user_id}/channel_list) and full views ({user_id}/channels).

Once you have that, just support JSON instead of (or in addition to) HTML as the representation format, and you have REST.

Answer 3

I would recommend Restful Obects which is standards for exposing domain model's restful

The idea of Restful Objects is to provide a standard, generic RESTful interface for domain object models, exposing representations of their structure using JSON and enabling interactions with domain object instances using HTTP GET, POST, PUT and DELETE.

According to the standard, the URIs will be like:

• api.example.com/object/user/31
• api.example.com/object/user/31/properties/username
• api.example.com/object/user/31/collections/channels
• api.example.com/object/user/31/collections/members
• api.example.com/object/user/31/actions/someFunction
• api.example.com/object/user/31/actions/someFunction/invoke

There are also other resources

• api.example.com/services
• api.example.com/domain-types

The specification defines a few primary representations:

• object (which represents any domain object or service)
• list (of links to other objects)
• property
• collection
• action
• action result (typically containing either an object or a list, or just feedback messages)
• and also a small number of secondary representations such as home, and user

This is interesting as you’ll see that representations are fully self-describing, opening up the possibility of generic viewers to be implemented if required.

Alternatively, the representations can be consumed directly by a bespoke application.

Answer 4

The best advice I can give is to try and avoid thinking about your REST api as exposing your objects. The resources you create should support the use cases you need. If necessary you might create resources for all three options:

api.example.com/completeuser/{id}
api.example.com/linkeduser/{id}
api.example.com/lightweightuser/{id}

Obviously my names are a bit goofy, but it really doesn't matter what you call them. The idea is that you use the REST api to present data in the most logical way for the particular usage scenario. If there are multiple scenarios, create multiple resources, if necessary. I like to think of my resources more like UI models rather than business entities.