REST URL: Can REST resource uniquely identified by the path variable defined in the URI?

user_64960 0
Viewed 37

I am modeling the following hierarchy in the REST URL:

Document-Type is a group of related documents.

Document: JSON document with specific details.

example: IncomeTaxReturnsDocument, ShareMarketDailyStatusDocument, TopProfitCompaniesListDocument etc

Each Document-Type has a dedicated schema and differs from other documents belonging to different Document-Type.

example: IncomeTaxReturnsDocument has specific schema which differs from ShareMarketDailyStatusDocument.

To model this in REST interface, I followed below approach:

https://{base_url}/v1/document-types/{document_type_id}/document

where document_type_id can be IncomeTaxReturnsDocument, shareMarketDailyStatusDocument etc

The combination of document_type and document in the URL makes the resource unique.

Other option is: to model based on resource type.

https://{base_url}/v1/IncomeTaxReturnsDocument
https://{base_url}/v1/shareMarketDailyStatusDocument

But this approach forces me to create "n" number of URLs ( one for each document_type) and the list grows to 100s.

Is making URL unique by combining the document_type_id in the path variable and document together is a bad practice ? Does https://{base_url}/v1/document-types/{document_type_id}/document violates any REST guidelines?

web api-design resources rest uri
2 Answers

Does https://{base_url}/v1/document-types/{document_type_id}/document violates any REST guidelines?

REST doesn't care what spelling conventions you use for your resource identifiers, so long as they are consistent with the production rules defined in RFC 3986.

As far as machines/general purpose HTTP components are concerned, resource identifiers are semantically opaque. There are some purely structural concerns (this is the part that gets copied into the Host header; these are the rules we use to resolve dot segments).

What this means is that any spelling that makes sense to the humans you care about is fine.

Not sure if my question is clear enough. I would like to ask if approach of having document_type_id in the path variable is better or document_type as a resource instead of document.

Same answer: both are fine.

Consider this: HTTP is an application protocol for transferring documents over a network (Webber, 2011). It doesn't care what the documents are, what the documents mean, or what identifiers we use for the documents. Part of the point is that we have a common protocol that is used for all documents.

That in turn means that if you are trying to choose between two resource models, neither REST nor HTTP have any bias that favors one or the other. All they say is that, from the outside, it should look like a website.

user_547340

REST just tell you that you must use standards to describe an uniform interface. In this case the standard you follow is the URI standard and the URI template standard. https://www.ietf.org/rfc/rfc3986.txt https://www.rfc-editor.org/rfc/rfc6570 All of your URI templates are valid according to the standards, so you can choose any of them. Even the https://{base_url}/v1/{resource-id} is a perfectly valid URI template and you can identify all of your resources with this single route and have only a single controller. People usually choose the URI templates which are the most convenient from development perspective, so I would choose https://{base_url}/v1/document-types/{document_type_id} to describe the document template along with metadata like title, template creation time, author, ACL, etc. And https://{base_url}/v1/document-types/{document_type_id}/document to describe the actual form or PDF users can fill. Actually this is the best practice as far as I know. Maybe using content type on the first template something like text/html would be good to respond with a HTML form they can fill and application/pdf would be good for the printable format and application/json or application/ld+json for the REST response. So you would not need the second URI template, just the first one. Tbh. it does not make a big difference, I mean you can identify a single web resource with multiple URIs and change representation based on URI, so you could use https://{base_url}/v1/document-types/{document_type_id}/json and https://{base_url}/v1/document-types/{document_type_id}/html and https://{base_url}/v1/document-types/{document_type_id}/pdf too, but the HTTP and MIME type standards cover this area pretty well, so no need to reinvent the wheel.

user_6070330
Related