Nick Nick - 2 months ago 17
HTTP Question

Media Types for list endpoints

I've got a REST application with endpoints that return single items and pages of those same kinds of item.

Let's say that the single-item endpoint has a media/content type like this:

application/vnd.company.myitem-1+json


And we also currently have a content type for the page structure itself, which looks like this:
application/vnd.company.mylist-1+json


I really want to be able to specify what the list is a list of, but I haven't been able to find an acceptable way to say that it's a
application/vnd.company.mylist-1+json
of
application/vnd.company.myitem-1+json
. Is there any good way to do this or am I barking up the wrong tree entirely?

Answer

You could encode the list and entry type in a single component of the vendor tree part, such as

application/vnd.company.mylist1-myitem1+json application/vnd.company.mylist1-otheritem1+json

If your list type of item type already contain a dash, you might have to chose an alternative separator.

Alternatively you could simply transport the list type in the Content-Type: application/vnd.company.mylist-1+json header and use a different one for the item type such as X-Item-Content-Type: application/vnd.company.myitem-1+json for the item type.