REST API, path variable vs request param

Question

I am currently writing a webservice providing access to some resources. I try to follow REST but I am facing a problem concerning some parts of my API.

I have the follwing uris:

/myservice/users/ : to get all users
/myservice/users/{userId} : to get a specific user
/myservice/badges/ : to get all badges
/myservice/badges/{badgeId} : to get a specific badge

Now, my problem is, i have to implement a way to get all users that have a particular badge. I can consider that this is just a filter I apply on the list of users, hence the following uri:

/myservice/users/?filter=badge:{badgeId}

Or I can consider that this is just a sub-resources of a badge, hence the following uri:

/myservice/badges/{badgeId}/users/

Which one seems the must 'REST-compliant' ?

I must say I have read some posts on this subject specifically this one: Rest Standard: Path parameters or Request parameters but they don't seem to cover my problem.

REST has no opinion on what your URI looks like. Either one is just as "REST compliant" — Darrel Miller, Mar 27 '12 at 16:53
FYI, I took a shot at the question you mentioned, you might be interested in the [answer](http://stackoverflow.com/a/31118242). — tne, Jun 29 '15 at 14:46

Andaris · Answer 1 · 2012-03-29T00:00:50.763

If you're looking to be RESTful, consider using HATEOAS (horrible acronym, but key to being truly RESTful).

Using HATEOAS, your Badge representation could look something like this:

<badge>
  <id>1234</id>
  <name>Admin</name>
  <link rel = "/rel/users"
        href = "/myservice/users?badge=1234" />
  <link rel = "self"
        href = "/myservice/badges/1234" />
</badge>

This allows your clients to be decoupled from your server's URI scheme as they simply GET on whatever href the /rel/users link provides. Granted your server still needs to define a URI scheme internally, but if at some point down the road you decide you don't care for it, you can easily change it without breaking your clients. For instance, you may want to change your URI scheme to your second option, which would cause your Badge representation to change to this:

<badge>
  <id>1234</id>
  <name>Admin</name>
  <link rel = "/rel/users"
        href = "/myservice/badges/1234/users" />
  <link rel = "self"
        href = "/myservice/badges/1234" />
</badge>

Clients using the /rel/users link relation aren't affected by the URI change. What this boils down to is ... use HATEOS, and the URI scheme doesn't really matter all that much.

Cheers!

score 0 · Answer 2 · edited Nov 23 '18 at 08:03

0

I strongly recommend using query string.

Path variable binding is not good. Path variable breaks the Apache access log analysis data. No analysis tool supports path variable.

If your company uses APM - expensive - tool, path variable sees the same functionality as an independent API.

REST? OK. But binding must to use query string.

edited Nov 23 '18 at 08:03

Filnor

1,290
2
23
28

answered Nov 21 '18 at 10:28

HeeGu

1
1

score 0 · Answer 3 · answered Nov 23 '18 at 08:38

0

Use query string like:

/myservice/users/?badge=badgeId&genter=male&year__gt=18

This is more restful.

answered Nov 23 '18 at 08:38

ramwin

5,803
3
27
29

score 0 · Answer 4 · answered Mar 27 '12 at 16:33

0

I prefer /myservice/users/?filter=badge:{badgeId} and I think more APIs use this format.

answered Mar 27 '12 at 16:33

abraham

46,583
10
100
152

REST API, path variable vs request param

4 Answers4