Which of these URLs is the best according to the REST standards?

Question

I am trying to figure out the best/right way to design the URLs of my rest api but I am confuse in between a company resource.

This is a company resource located at http://localhost:8085/api/v1/company/1. This will return me some basic data from a table company.

Fine till now. But now the company can be of two types: 1. Mechanical 2. Other. Each has their respective table in DB with 1:1 relationship with company table. To fetch the further details about the company, I need to expose the other two tables from some API endpoint.

So, I am confused in between three URLs here:

http://localhost:8085/api/v1/company/1?type=mechanical
http://localhost:8085/api/v1/company/1/mechanical
http://localhost:8085/api/v1/company/mechanical/1

I reject option 1 for one reason I found on SO, i.e paths having parameters cannot be cached. Rest Standard: Path parameters or Request parameters

I am mainly confused in between 2 and 3? What would be the correct way?

One question you may ask, why not I am providing the complete company information from http://localhost:8085/api/v1/company/1? That's because I want to take advantage of Lazy Loading. Details for the company could take more time to fetch, so I separated the contents.

Firstly it should be `/companies`. `?type=mechanical` makes it seems like you're filtering, but `/companies/:id` is a single resource, so it's unclear what you'd be filtering (whereas `/companies?type=mechanical` would be *"all mechanical-type companies"*). Maybe the detailed data should be considered a sub-resource, `/companies/:id/details`; the client shouldn't really have to care whether that comes from one table or another. — jonrsharpe, Jun 05 '19 at 13:24
Yes, that should be `companies`. So, the 2nd option would be the most accurate way? — The Coder, Jun 05 '19 at 13:29
There are no REST standards for URLs. REST treats URLs as totally opaque. REST is an architectural style. — Eric Stein, Jun 05 '19 at 13:33

score 0 · Answer 1 · edited Oct 07 '21 at 13:33

I am trying to figure out the best/right way to design the URLs of my rest api but I am confuse in between a company resource.

REST doesn't care what spellings you use for your URLs, so long as they are compliant with RFC 3986. URI are identifiers, it is not required that the spelling of the identifier be in any way related to its semantic meaning.

Human readable URI are much like human readable variable names - not required, but certainly convenient where people are involved. So spellings should primarily be chosen in accordance with local conventions.

To fetch the further details about the company, I need to expose the other two tables from some API endpoint.

Part of the point of REST is that your resource model might not be tightly coupled to your data model. "On the internet, no one knows you are a dog". You certainly can create a resources for every part of your relational schema.

Just be aware that nobody with experience will promise that the result will be viable in the long term.

I reject option 1 for one reason I found on SO, i.e paths having parameters cannot be cached.

I'm all but certain that's a very bad answer, and therefore bad support for a given design. But again, REST doesn't care about the spelling.

http://localhost:8085/api/v1/company/1?type=mechanical
http://localhost:8085/api/v1/company/1/mechanical
http://localhost:8085/api/v1/company/mechanical/1

All of these are fine.

One reason to prefer one order of path segments over another would be to take advantage of dot segments and relative resolution; which is to say, what happens if we take the URI above, and try to resolve the relative-path-reference ..

http://localhost:8085/api/v1/company
http://localhost:8085/api/v1/company/1
http://localhost:8085/api/v1/company/mechanical

Given what you've described here, option #2 looks more useful than its cousins.

If relative resolution isn't an important use case, then you might consider using a new stem

http://localhost:8085/api/v1/mechanical-company/1

Firstly it should be /companies

Only if that's a local spelling convention.

/company/1
/companies/1
/c5y/1
/c6s/1
/compagnie/1
/c5be6eed-3df2-4987-aceb-1b2f8909cb85/1
/purpleMonkeyDishwasher/1

None of the machines care which of these spellings you use.

Which of these URLs is the best according to the REST standards?

1 Answers1