In our ASP.NET Web (REST) API Best Practices series, today we are going to talk about the Resource naming. This is most important concept in designing the REST API Endpoints, It's like designer who design UI for their applications. Similar way REST API developer need to design their endpoint in way that consumer of API (developer, end user) can easily predict API Endpoints without much reading API documentations and easily integrate in their applications.
So, How we design the API which are predicative and same time easy to integrate?
Well, we need to identify resource of services, and we need to exposed those services resource via endpoints.
We need to identifying the resources within the system and need to expose them as nouns, not as verbs or actions. what is that means? let's understand with help of the example.
Suppose we need to design the endpoints for Leaning System which have following entities,
- Student
- Teacher
- Course
and we need to expose above resources in services by,
Creating the new student in learning system,
POST http://www.api.learning.com/students
POST is act as actions and we select students as nouns
Similar way to read the all students we changes only http methods type
GET http://www.api.learning.com/students
If we want to fetch single records of students, we need to pass the ID of student in URL
GET http://www.api.learning.com/students/123
And similar way we can update/delete the student records
PUT http://www.api.learning.com/students/123
DELETE http://www.api.learning.com/students/123
What If we need to fetch the course of student ? how to design the URL?
Yes ofcourse we simply create below URL
GET http://www.api.learning.com/coures
but we can not determine which courses are associate with which students, if there is any relationship exist between two entities we need to go one step deeper in endpoints URL, for ex.
GET http://www.api.learning.com/students/123/courses
above URL return only courses which student having ID 123 is associated.
Easy right, add your comments if youhave awesome tips regarding naming convention you follow.
Comments
Post a Comment