Good URL syntax for a GET request with a composite key

Question

Let's take the following resource in my REST API:

GET `http://api/v1/user/users/{id}`

In normal circumstances I would use this like so:

GET `http://api/v1/user/users/aabc`

Where aabc is the user id.

There are times, however, when I have had to design my REST API in a way that some extra information is passed with the ID. For example:

GET `http://api/v1/user/users/customer:1`

Where customer:1 denotes I am using an id from the customer domain to lookup the user and that id is 1.

I now have a scenario where the identifier is more than one key (a composite key). For example:

GET `http://api/v1/user/users/customer:1;type:agent`

My question: in the above URL, what should I use as the separator between customer:1 and type:agent?

According to https://www.ietf.org/rfc/rfc3986.txt I believe that the semi-colon is not allowed.

Why not use query parameters, e.g. `/v1/users?customerId=1&type=agent`. `/user/users` seems suspicious, and making up your own representation is generally not a good idea. — jonrsharpe, Feb 18 '19 at 12:31
I was thinking about it and I think this question is more in regards to what to do when your resource id is a composite key — Richie, Feb 18 '19 at 20:52

score 1 · Answer 1 · answered Feb 18 '19 at 12:34

1

You should either:

Use parameters: GET http://api/v1/user/users?customer=1

Or use a new URL: GET http://api/v1/user/users/customer/1

But use Standards like this

("Paths tend to be cached, parameters tend to not be, as a general rule.")

answered Feb 18 '19 at 12:34

Joël-Etienne

386
1
12

score 0 · Accepted Answer · answered Feb 19 '19 at 04:27

Instead of trying to create a general structure for accessing records via multiple keys at once, I would suggest trying to think of this on more of a case-by-case basis.

To take your example, one way to interpret it is that you have multiple customers, and those customers each may have multiple user accounts. A natural hierarchy for this would be:

/customer/x/user/y

Often an elegant decision like this can be made, that not only solves the problem but also documents your data-model in a way that someone can easily see that users belong to customers via a 1-to-many relationship.

Good URL syntax for a GET request with a composite key

2 Answers2