Rest API resource naming with multiple IDs

Question

After reading :

https://restfulapi.net/resource-naming/

I have a question regrading referencing documents in collections when a document has multiple unique IDs.

In the linked material an example is given:

We can identify a single “customer” resource using the URI “/customers/{customerId}”.

or

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

And my example:

http://myserver/api/courses/{id}

Which has a js Express function counterpart:

app.get('/api/courses/:id', (req, res) =>... 

My question is how do I maintain a consistent API if my document (courses) has two unique ID keys that I would like to use.

Such as ID1 & ID2.

How would I code that in express and how would I write the url?

So if I need the two APIs to be:

http://myserver/api/courses/{id1}
http://myserver/api/courses/{id2}

If I provide two Express routines:

app.get('/api/courses/:id1', (req, res) =>... 
app.get('/api/courses/:id2', (req, res) =>... 

And ID1 and ID2 are both the same type (eg. numbers). How does the REST API distinguish these two?

Answer 1

REST doesn't care about the spelling of your resource identifiers. Conventions, like those described by https://restfulapi.net/resource-naming/ , are roughly analogous to coding conventions about spelling variable names.

From the point of view of a REST client, /api/courses/X and /api/courses/Y are different resources -- those resources might share the same underlying representation (because they are constructed from the same underlying data), but that's an implementation concern of the server.

URI spellings are only constrained by RFC 3986.

/api/courses?id1=12345
/api/courses?id2=67890

That's a perfectly reasonable choice. One potential upside is that HTML includes a standard for creating URI templates with query parameters. A potential downside is that relative reference resolution treats the non-hierarchical data in the query-part differently than the hierarchical data in the path segments.

/api/courses/id1/12345
/api/courses/id2/67890

Perfectly reasonable choice, with the opposite tradeoff from above.

/api/courses/id1=12345
/api/courses/id2=67890

This is really the same idea as above, with a slightly different spelling. It has the advantages of being easy and human readable. However, actually working with that pattern may be challenging, depending on what kind of routing support you have.

As URI templates, these would probably look like

/api/courses/id1={id}
/api/courses/id2={id}

But in places where you have level 4 URI template support, you might be able to use

 /api/courses/{/ids*}

Another possibility would be to use a "matrix parameter" inspired spelling, like

/api/courses;id1=12345
/api/courses;id2=67890

Again, this gives you a different set of trade offs of readability, template support, relative resolution support, and so on.

See also Stefan Tilkov -- REST: I Don't Think It Means What You Think It Does.