5

I am designing a REST API but came across some difficulties while naming it. I have an API like this:

GET   .../users/{userId}/categories/count
GET   .../users/{userId}/categories/{categoryId}/count
GET   .../users/{userId}/categories/{categoryId}/tickets

It seems like the API is about users' categories, but actually the usages are:

Get the number of tickets for each available ticket categories for specified user

Get the number of tickets for the specified ticket category for specified user

Get all the tickets under the specified ticket category for specified user

For the first 2 APIs, I might change this to:

.../users/{userId}/tickets/categories/count

.../users/{userId}/tickets/categories/{categoryId}/count

But for the last one, I am not sure how to design the API path. Is it weird if I change it to:

.../users/{userId}/tickets/categories/{categoryId}/tickets
Glorfindel
  • 3,137
  • 6
  • 25
  • 33
hades
  • 151
  • 4

1 Answers1

6

From your description category seems more like an attribute of a ticket than a discrete entity. Therefore I would use a query parameter to filter the tickets by category.

.../users/{userId}/tickets                             #1
.../users/{userId}/tickets?category=categoryId         #2
.../users/{userId}/tickets/count                       #3
.../users/{userId}/tickets/count?category=categoryId   #4
  1. Gets all user's tickets in all categories
  2. Gets all user's tickets in the given category
  3. Gets the count of user's tickets in all categories
  4. Gets the count of user's tickets in the given category
Samuel
  • 9,137
  • 1
  • 25
  • 42