When do I use path params vs. query params in a RESTful API?

by

Best practice for RESTful API design is that path params are used to identify a specific resource or resources, while query parameters are used to sort/filter those resources.

Here’s an example. Suppose you are implementing RESTful API endpoints for an entity called Car. You would structure your endpoints like this:

GET /cars
GET /cars/:id
POST /cars
PUT /cars/:id
DELETE /cars/:id

This way you are only using path parameters when you are specifying which resource to fetch, but this does not sort/filter the resources in any way.

Now suppose you wanted to add the capability to filter the cars by color in your GET requests. Because color is not a resource (it is a property of a resource), you could add a query parameter that does this. You would add that query parameter to your GET /cars request like this:

GET /cars?color=blue

This endpoint would be implemented so that only blue cars would be returned.

As far as syntax is concerned, your URL names should be all lowercase. If you have an entity name that is generally two words in English, you would use a hyphen to separate the words, not camel case.

Ex. /two-words

More Related Contents:

  1. What are best practices for REST nested resources?
  2. What is the proper REST response code for a valid request but an empty data?
  3. How to create REST URLs without verbs?
  4. API pagination best practices
  5. What’s the best RESTful method to return total number of items in an object?
  6. Spring @ExceptionHandler does not work with @ResponseBody
  7. Spring 4 RestController JSON: characteristics not acceptable according to the request “accept” headers
  8. Jersey with Struts2 [duplicate]
  9. Difference between Swagger & HATEOAS
  10. Delete multiple records using REST
  11. Call a Server-side Method on a Resource in a RESTful Way
  12. RESTful – What should a DELETE response body contain
  13. Hyphen, underscore, or camelCase as word delimiter in URIs?
  14. RESTful URL design for search
  15. HTTP response code for POST when resource already exists
  16. How does the Spring @ResponseBody annotation work?
  17. What is the advantage of using REST instead of non-REST HTTP?
  18. Unable to upload zip file through karate framework
  19. Firefox Add-on RESTclient – How to input POST parameters?
  20. Expose all IDs when using Spring Data Rest
  21. Should I use Singular or Plural name convention for REST resources?
  22. How to download excel (.xls) file from API in postman?
  23. Is it correct to return 404 when a REST resource is not found?
  24. When is it appropriate to respond with a HTTP 412 error?
  25. Websocket vs REST when sending data to server
  26. Trying to use Spring Boot REST to Read JSON String from POST
  27. The MAC signature found in the HTTP request ‘…’ is not the same as any computed signature
  28. Response status code for searches in REST APIs
  29. Status code when deleting a resource using HTTP DELETE for the second time
  30. Avoid duplicate POSTs with REST

Leave a Comment