I am strucuring our rest API resources and came accross an interesting dilemma. Here is the scenario and I am going to use a car analogy

   "id": 1,
   "make": "Toyota",
   "year_build": 2015

   "id": 1,
   insurances: [
   "policy_number": 101,
   "company": "Insurance Company 1",
   "valid_until": "2015-01-01"
   "policy_number": 102,
   "company": "Insurance Company 2",
   "valid_until": "2016-01-01"

I notice that resources can be reached with both
/cars/1/insurances/102 and /cars/1/insurances?policyid=102, but /cars/1/insurances/102 is more handier if we want to use additional subresources such as /cars/1/insurances/102/agents/....

My question really is do I have to follow the full path of url if each policy has a unique number, for example could i use


to get this policy instead of


Would take make a policy a primary resource instead of a car?

1 Answer 1


REST doesn't care what spelling you use for your identifiers -- they are opaque, from the point of view of the client, so the server can do whatever it likes.

There are conventions in play for URI design to make them more easily understood by human's. See Designing a REST API by URI vs query string.

My question really is do I have to follow the full path of url if each policy has a unique number

If policies are unique entities in your model, then modeling each as an element in the policies collection is a reasonable thing to do: /policies/104

It's normal, in REST, to have multiple URI (therefore multiple resources) that share the same representation. For instance, there might be a form that says "enter your policy number" which when submitted goes to /policies?policyNumber=105 which could then either redirect the user to some other resource /policies/105 or could present the content of the other resource (via Content-Location) or could present a representation of its own (which might duplicate the representations of other resources).

URIs do NOT map onto domain objects - that violates encapsulation.... You should expect to have many many more resources in your integration domain than you do business objects in your business domain. --Jim Webber, 2011.

Note that in REST, the expectation is that clients are negotiating your protocols by following hypermedia links. If you aren't giving clients links to follow, but instead are making clients guess the next URL, then you should prioritize using a set of spellings that are consistent and easy to remember.

Yes, in particular when it's natural to think in terms of subresources, it's most convenient that the identifier is contained within the hier-part of the URI.

  • So basically /cars/insurances/102 and /cars/1/insurances?policyid=102 could and up having different response despite the fact that that it is referencing the same domain object. Having consistent path structure should help when creating the response of the particular resource..
    – John
    Commented Apr 6, 2017 at 15:02
  • Yes. The first URI may retrieve a collection of insurances with a single entry instead of the insurance Itself
    – Laiv
    Commented Apr 6, 2017 at 17:57
  • If you use queries, you are modifying / filtering the representantation of the resource. So, make sense to think that the Uri with query retrieve a collection (allways)
    – Laiv
    Commented Apr 6, 2017 at 18:01
  • @Laiv we are not really discussing the use of queries here...
    – John
    Commented Apr 7, 2017 at 5:58
  • It was not my intention. Just explaining why the both URI may have different representantions. Due to the first use plural and filters It may lead to the think we are working with collection, so It make sense to expect a collection instead of a single object
    – Laiv
    Commented Apr 7, 2017 at 6:16

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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