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
– jonrsharpe, Commented Feb 18, 2019 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
– Richie, Commented Feb 18, 2019 at 20:52

Joël-Etienne · Accepted Answer · 2019-02-18 12:34:13Z

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.")

Evert · Accepted Answer · 2019-02-19 04:27:42Z

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.

Collectives™ on Stack Overflow

Good URL syntax for a GET request with a composite key

2 Answers 2

Comments

Comments

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Linked

Related