5

Is it sensible to use * in REST API for a resource ID? I want to use it for searching. I'm using RESTEasy for developing my webservice.

Suppose I have resources that are user and user has Name and Age. Then my REST API looks like:

/users/{id}/name
/users/{id}/age

Now if I want to display all names I'm thinking on using the following:

/users/*/name

Is this correct or should I use another way of doing?

Edit 1: Adding subresources

As from an answer it is suggested to use a fields query param. But let's suppose I'm now want something that is a property of the sub-resource. For instance:

/user/*/name/full
/user/*/name/short

If I follow the fields option, I will have to do:

/user?fields=name-short 
/user?fields=name-full

Which it is not nice as the properties of name are linked to the name class somehow.

Please do consider the example as that. Try to get the idea ;)

jlanza
  • 1,208
  • 3
  • 23
  • 43

1 Answers1

3

Query parameters

You can probably use wildcards, but not in the way you've shown in your question. What if you want to get more details besides the name in the same request?

You could use a query parameter to allow field selection for the users collection:

/users?fields=name

/users?fields=age

/users?fields=name,age

Or you can get some inspiration from how partial responses are handled in the Google Drive API:

/users?fields=name(short,full)

Alternatively, you could use dot notation:

/users?fields=name.short,name.full

Or use a mix of both, like in the Spotify API.

Custom media types

If you don't need field selection, you can use custom media type, returning a predefined set of fields.

cassiomolin
  • 124,154
  • 35
  • 280
  • 359
  • This is what I more or less do now. But the problem is that then I wanted to somehow add another subresource for the name. This way everything is hierachical. For instance, /users/{id}/name/full or short. I know I can create different resources, but then it doesn't look good. I'm updating my question. – jlanza Sep 15 '17 at 08:35
  • The provided Google Drive API reference shows this as well. – jannis Sep 15 '17 at 12:59
  • I will follow your advices, but I still don't understand why I cannot use a wildcard as a path param. Moreover, I have found https://stackoverflow.com/questions/207477/restful-url-design-for-search where it seems that you can use brackets, and many other for selecting some resources... Why not *? ;) – jlanza Sep 18 '17 at 07:26