Question

I am designing my first RESTful API (with the hypermedia constraint).

I am not sure if I framed the question correctly but here is an example.

Assume I had a product resource:

/products/{id}

There is a product_type element in the response.

Possible product types include (industry specific)

1. Floor Display
2. Dump Display
3. Light Bulk
4. …

My question is, what is the best way for the client to retrieve all of the possible attributes for the product resource?

I thought about exposing a “Metadata” sub-resource. For example:

product/metadata/type
product/metadata/status
product/metadata/material
product/metadata/color

… for every attribute that contains N items.

I’m afraid that my solution is too tightly coupled to the product collection. I am restricting attribute listings that could be used in another context (collection).

Another option is to provide a Metadata collection that contains all possible attributes but I’m not sure if that’s the best way of handling it.

Any pointers would be greatly appreciated.

Answer 1

How about simply returning the metadata as part of a GET on that resource?

For example, if I GET /products/123, I might receive the following payload in the response (assuming a JSON media type):

{
   "type" : "Floor Display",
   "color" : "Blue",
   "material" : "wood",
   ...
}

And so forth. Now if you need to more information about each attribute then you could make each one a subordinate resource and have the URIs returned rather than the simple values that I’ve listed above.

Edit:

Now if you want to make the client aware of all possible values then that should be specified outside of your response as part of your media type documentation. It’s not going to be useful to put that kind of “schema” information into your responses.

Along the same vein, an HTTP response can return codes like 200, 404, 503, etc but the response does not list all possible codes nor does it define their semantics. Instead, that’s the job of the HTTP specification.

I would take the same approach and define the structure and semantics of your media types in your API documentation and only transmit the value(s) relevant to the response. I can’t think of any benefit to including all possible values directly within the response.