I am designing an API and am having a couple of problems with certain parts of the resource modelling.

I have the notion of a SurveyItem which as a collective form a Survey:

Survey Resource Endpoint:

Accessing Survey Items

Pretty basic and i am not overly concerned with the above. SurveyItems cannot exist outside the context of a survey hence the hierarchy.

Where i am struggling a little is the next level down. A SurveyItem is not necessarily one thing (bear with me) as it is based on an interface which is implemented but you may have something like a "Simple Survey" that lets you take notes, a "Video Survey" will let you take a survey via video etc, so they are all the all part of the base implementation but could potentially have different sub resources.

Image and note survey type sample endpoints

Video Survey

As you can see above a SurveyItem may have different sub endpoints depending on the type of SurveyItem it is. I was thinking of modelling it the way above but using a HATEOAS approach of responding with a collection URLs of the available sub endpoints for each individual survey type so they are discover-able by clients.

Is this a reasonable thing to do or are there better approaches to handling things like this?

  • 1
    Maybe relevant: stackoverflow.com/questions/13488697/… I am not sure whether you should go this deep. It makes working with the API quite complex as I feel right now. Also I would consider using: /survey/1/items/232 since it's clear it is dependent. Makes it also a bit more readable. Jul 5 '13 at 18:40
  • Hi Luc, thanks for the comment and link. I understand making this more granular may up the complexity. We are looking on leaning on Hypermedia to supply navigational links for resources so sub or linked resources are easily discover-able, the only thing that concerns me about making them a core part of the SurveyItem resource is that item could become heavy to respond with. Also re the naming convention, the verbosity of surveyitems is not something we would have in the API, it was just above to illustrate the flow. Jul 12 '13 at 10:06

Sounds perfectly reasonable.

In a hypermedia-driven service, the form of your URLs is not really important.

You could also have a flat structure:


Or just use global ids:

http://api.somewhere.com/1 (a survey)
http://api.somewhere.com/2 (a video surveyitem for survey 1)
http://api.somewhere.com/3 (a video for surveyitem 2)
http://api.somewhere.com/4 (a note)

The hierarchy you've proposed conveys much more useful information about the identity of your resources and their relationships than either of these other options.

Moreover, it will probably be easier to implement because all of the unique identifiers in the URL will map nicely to normalised database tables.

You could give each type of SurveyItem its own URL pattern:


But this seems to imply that all surveys will contain distinct collections of every type of items, which doesn't seem true from your description.

If, in the future, you decide (for example) that videos are actually independent of surveys, you can always change your mind by changing your links and/or setting up a redirect:

= HTTP 303 See Other: http://api.somewhere.com/videos/1
  • Thanks ajlane, this is the route we are actually going down. Because we are specifically using hypermedia it seems to flow better using sub resources available via links then trying to stuff that stuff under one resource entry point. Aug 9 '13 at 12:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.