CODEWITHSUNDEEP
rest
simondefreeze
simondefreeze

Reputation: 189

Appropriate endpoint for url which contains sub resource that mentions parent resource

A user can be assigned to a job, this is represented by a memberJobAllocation. I want to create an api endpoint to get all memberJobAllocations against a job; I was thinking to use the url 'Job/{id}/memberJobAllocations'. This seems like a strange api endpoint as the first part ('Job/') already indicates the allocations are for the job.

Could the url just be 'Job/{id}/memberAllocations'? This might read better but what happens if I want to create another endpoint to get a memberJobAllocation, it would have to be 'memberJobAllocation/{id}' since 'memberAllocation/{id}' doesn't say much. Is it okay to have two different names for the memberJobAllocation resource in my API?

Which approach would be better? Does rest enforce the name of the resource should match exactly or is there some flexibility?

Upvotes: 0

Views: 51

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57239

Does rest enforce the name of the resource should match exactly or is there some flexibility?

REST only insists that identifiers comply with the production rules described by RFC 3986.

For ease of comprehension by your human consumers, you'll want to use a spelling that is consistent with the "look and feel" of the other parts of your API, but the machines don't care.

Therefore:

I was thinking to use the url 'Job/{id}/memberJobAllocations'.

Yup, that's fine.

Could the url just be 'Job/{id}/memberAllocations'?

Also fine.

Is it okay to have two different names for the memberJobAllocation resource in my API?

No, but sort of. As far as REST is concerned, if you have two different resource identifiers, then you have two different resources (documents). But it is perfectly OK for two different documents to present the same information (ie, are built from the same underlying sources).

As far as the client (and more broadly, all general purpose components) are concerned, the two documents are completely independent of one another -- invalidating one will have no effect on cached representations of the other. If a single client likely to be retrieving the same information from two different resources, then you'll need to give a think to what it means if the information in the two resources is "out of sync".

Upvotes: 1

Related Questions