Will this be considered as bad RESTFul design?

Question

I am working on designing the API's for the first time in Spring and I have the following use case:

1. Get all the products.
2. Get Products by ID.

Now, what I did was, I made a single API for this,

@Path("/products")
public interface ProductResource {

    @GET
    @ApiOperation(value = "Gets all the products by criteria")
    Response getProductsByCriteria(@Context UriInfo uriInfo);
}

What I am doing is, I take the ID in the query param. If it's value is null, I will call the method (at service layer) for returning all products, else I will call the method for returning a specific product based on its id (coming in the query param).

I just want to know, is this a bad RESTFul Design? Should I instead have two seperate API's for getting products based on their ID's and for getting all the productS?

Answer 1

I would suggest to have separate endpoints:

• GET /products for all products
• GET /products/{productId} for getting product by specific id which would be passed as PathParam. In this way, you could have other endpoints for manipulating product data, for example PUT /products/{productId} or DELETE /products/{productId}. They would return HTTP status NOT FOUND (404) if product is not found.

QueryParam is more suitable to filter products by some characteristic, for example GET /products?color=red.

Answer 2

You should definitely have

• GET /products - returns list of all products
• GET /products/:id - which returns single product or 404 in case the product is not found

In this way it's much easier to read and it's consistent with other quality APIs you find on the internet.

Answer 3

By mixing the getAll and getById, you are missing an important point: there is no way for the caller of the API to know if a productId exists. Normally you would return a 404 on a get for a product id that does not exist.

So to answer your question: yes, it is a Restful design mistake.