8

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?

Improve this question
4
  • 1
    Can you let us know why you have these different IDs? Are they relevant for the outer world? Otherwise, you can just stick to one ID. Commented Jul 10, 2019 at 11:08
  • @charlietfl That's not true. An element can have multiple unique IDs - each unique in terms of a well-defined scope Commented Jul 10, 2019 at 11:11
  • I'd be interested to know how you store your courses then, how would you query for it in the DB? If it's looked up in the same way then you would still just use the single route e.g. /api/courses/1234 and /api/courses/5678 could reference the same course but still use the same API Commented Jul 10, 2019 at 11:11
  • 1
    Courses/Products in many countries have a local ID and an international ID. Inventory systems do it all the time!!! Sellers part number, the suppliers part number. Both unique and many times different!!! Commented Jul 10, 2019 at 12:40

3 Answers 3

Reset to default
5

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

1 Comment

The naming conventions of a REST API is not the same as how express determines it. The way the OP has his routes written, express will not be able to distinguish those routes. Express stores routes in a stack, and will match with the route first declared (id1). The id1 is only a name to represent generic data (like a scoped variable).
1

You need another differentiation in the url either in the path or as a query param in order to know which field is being sent. The default would be for field #1 and the other for field #2

app.get('/api/courses/:id1', (req, res) =>... app.get('/api/courses/other-key/:id2', (req, res) =>...
Improve this answer

Comments

0

The naming conventions of a REST API is not the same as how express determines it. The way the OP has his routes written, express will not be able to distinguish those routes. Express stores routes in a stack, and will match with the route first declared (id1). The id1 is only a name to represent generic data (like a scoped variable).

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.