REST API best practise for routes

Question

I wonder what is the best practise when creating REST APIs for the following scenarios when an Order is a resource:

1. Get all the orders in the Database. (surely not a practical scenario, only for understanding purpose)
2. Get orders by order IDs.
3. Get a single order by order ID

• Can a single GET route be used for all these scenarios?

• Or should we have separate routes for these scenarios?

Any help would be much appreciated!! (Express JS framework is used if that matters)

Answer 1

Can a single GET route be used for all these scenarios?

You could use a single route for all these scenarios:

GET /orders                              // get all
GET /orders?id=409,5678,2987             // get these orders by id
GET /orders?id=9463                      // get this order by id
GET /orders?person=jackwelch             // get orders for this person
GET /orders?company=aaWidget             // get orders for this company 

Or should we have separate routes for these scenarios?

This is largely a matter of design opinion. I'm generally a fan of keeping the number of distinct URL forms to as few as practical and overloading the same route for different inputs when it makes sense and doesn't feel too arbitrarily stretched to make it all a fit. But ultimately, it's a judgment call based on an understanding of the overall landscape of queries you need to support and how it will most likely be used.

And, keep in mind that for adding a new order, you would use POST and modifying an existing order, you would use PUT and deleting an order, you use DELETE

POST   /orders                    // create new order, data in body of request
PUT    /orders/:id                // modify existing order, data in body of request
DELETE /orders/:id                // delete an order

So, all of these can be done with one /orders URL structure to the outside world. Internally, it would probably be structured as several different route handlers, just to make the code for handling it simpler:

app.get("/orders", ...);         // handle order queries   (use req.query)
app.post("/orders", ...);        // create new order       (use req.body)
app.put("/orders/:id", ...);     // modify existing order  (use req.params.id and req.body)
app.delete("/orders/:id", ...);  // delete existing order  (use req.params.id)

Another nice thing about this structure, is that it's very extensible. You can add more ways to query the orders by only adding additional query string parameters with no overall change to the structure or even any new route handlers.

Answer 2

RESTful APIs use HTTP methods as verbs. This means that the same endpoint shall be used to get a list of orders and create a new one; or get one specific order, update it or event delete it.

With this in mind, you could design your API structure as follow:

GET       /orders        // To get a list of all orders
GET       /orders/:id    // To get information about a specific order

This will help you to add more methods quite easily, without changing the API design:

POST     /orders         // To create a new order
PUT      /orders/:id     // To update that specific order
DELETE   /orders/:id     // To delete it

In case you want to add search capabilities on an endpoint, it's quite common to use query string. For examples:

GET   /orders?email=john@example.org  // To retrieve all orders from that customer
GET   /orders?limit=10                // To retrieve only 10 hits per results
GET   /orders?limit=10&total=99.99    // To retrieve top 10 orders with a total of 99.99

You could add a dedicated search parameters to return orders by IDs (as asked), but it's not so common as you can already query by ID using the endpoint /orders/:id. You might think about avoiding extra requests here, but generally speaking the performance gain is quite low - except if it's critical to your application to retrieve by IDs several hits.