Properly structure path for rest API resources

Question

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

/cars/1/
{
   "id": 1,
   "make": "Toyota",
   "year_build": 2015
...
}

/cars/models/1/insurances
{
   "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

/cars/insurances/102

to get this policy instead of

/cars/1/insurances?policyid=102

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

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.