restful api design: when to use path vs query parameters

When designing a RESTful API, it can be useful to have rules of thumb for what kinds of attributes should be included in the path vs. what should be specified in the query parameters.

One rule that makes sense to me is that path params are used to identify resources whereas query params are for filtering and sorting them.¹

So, if the domain is todos, we might have:

GET /todos
GET /todos/:id
POST /todos
PUT /todos/:id
PATCH /todos/:id
DELETE /todos/:id

Then, later you want to query based on a property of a resource, that’s where query params come in:

GET /todos?complete=false

Of interest: since the id could be considered a property of a resource, a useful way to distinguish what counts as a resource identifier and a resource property is whether it is unique.

In the case of the Todo domain used in this example, I’m assuming that the id of the todo is unique to each Todo (therefore it uniquely identifies a resource). On the other hand, many Todos may be complete or not.

Footnotes

• ¹ This was well summarized in this Stack Overflow conversation on the topic of API design.