RESTful API Resource Path for Complex Relationships

apirest

In my RESTful API, I have Users, Applications, and Tokens. An application has an owner, which is a user. A token is linked to both an application, and a user.

A user has both public and private representations:

  • GET /user – Retrieve current authenticated user
  • GET /users/:user – Retrieve given user

An application has a public representation:

  • GET /applications/:id – Retrieve given application

A token is associate with both a user, and an application. A token is never public:

  • GET /user/tokens/:id – Retrieve given user token

Similary, applications of a user can be seen like so:

  • GET /user/applications – Retrieve collection of the current authenticated users' applications.

What should the resource path be in a situation such as this, for if I wanted to get all of the current users' tokens for a given application? Some things I have considered:

  • GET /user/tokens/application/:appId – I felt this may be poorly represented. How would it be read? Current users' tokens application? It's really: current users' tokens for application.
  • GET /user/applications/:id/tokens – I felt this could imply that if you owned an application you would be able to see the tokens of all users using the application, which is of course not the intended functionality, or representation.
  • GET /applications/:id/tokens – I felt this to be problematic in a manner similar to the above.

Best Answer

Remember you can use the query string to filter or limit the result. Since you're looking for a user's tokens, limited to a particular application, this is pretty natural

GET /user/tokens?application=:id

The resource is a collection of tokens, limited by an application ID. This is consistent with /user/tokens/:id except that you're narrowing the result by application ID instead of a token id.

Related Topic