What operations should a RESTful API have?

Question

I'm new to express and apis, and I'm currently building a RESTful API with Express. For example let's say this is my model.

Sheep = {
 name: String,
 age: Number,
 color: String
}

Aside from basic CRUD operations I saw from this tutorial , like create a Sheep, read a Sheep by id, update a Sheep by id, and remove a Sheep by id are there other operations I should include in my api?

In particular I'm wondering if I should make routes for find a sheep by name/age/color for example and how in best practice I would handle the routes for that.

I'm probably lacking information, but by the tutorial above, the route to find a sheep by id is "/sheeps/:sheepId" . How would I make a route to find by name? If I do "/sheeps/:sheepName" would that not be identical to find sheep by id because if I go to my browser and go for example: "localhost:8080/sheeps/someNameOrId" how would the browser or in particular the client side recognize if it is a name or an id?

I'm working with AngularJS as my client if that could help build a more helpful answer.

Answer 1

Yours is a very classical case where we need to write RESTful resources for each opertaion. As you rightly said there is no way for REST to know if you are passing ID or Name. Ideally, in this case, you need to group the operations per resource.

In your case, you need to do CRUD byId or byName, then you need to write your REST resource as "/sheeps/ id /:sheepID" or "/sheeps/ name /:sheepName".

Answer 2

First of all, while REST has its standards and best practices, it is not a protocol. So, people might suggest different solution to a problem and they all might be right in there own sense.

Now coming to your question, in principal the uri should represent a resource on which you want to do an operation. It may or may not have the query parameters for a search, filtering etc. So, the representation /sheeps/{sheep id/name} is perfect for the sheep. Now for your problem statement, below could be valid RESTful ways of implementation:

• /sheeps?sheepId='123' AND /sheeps?sheepName='Eve'
• /sheeps/{sheepId} AND /sheeps/name/{sheepName}

Syntactically they are all fine. Now, if we think without getting too focused about the term REST, we would find that in both of our options the performance of our API is going to be same. So, it is more about readability, which means which option gives a better view of what we are doing. I think in both the cases a programmer would easily understand what we are doing.

So, get rid if the thought that only one option is right and choose what you think is better.

Other thing to notice in the above implementation is that when you do a search, like /sheeps?sheepId='123', and if you don't find something matching the parameters, you would ideally pass 204 No Content. While in case of /sheeps/{sheepId} it should be 404 Not Found. What makes more sense in your case? Choose as per your understanding.

This was for the sheepId and sheepName conflict. Now for the requirement of getting sheeps by name/age/color, the below approach seems very logical.

• /sheeps?age='5'
• /sheeps?color='black'
• /sheeps?age='5';color='black'