There is a debate on the API naming in the world of REST – more than there should be. As per the famous dissertation – and I paraphrase – any information / artifact / entity / process (and so on) that can be named (or addressed) can be a resource. And there could be collection of resources that could be addressed as well. For instance: a business process of “student enrollment” can be a resource and a “student” or a collection “students” are resources as well.
While designing a REST API, we generally like to rush through the naming and that is not all right since frequent revisions to the name space would certainly affect the consumers thereby this becomes a critical piece.
We also need to consider the granularity of the API: the more finely granular the more the more populated the name space would be and perhaps require clients that are smarter and knowledgeable of the business processes if they are present. I would in brief present an example that would elucidate the above.
Suppose we have to design an API that would deal with student enrollments into courses. Relative URIs follow:
|
1 2 3 4 |
POST: /studentEnrollment/ =========> response is a 201 with the "Location" pointing to the id of this process GET: /studentEnrollment/{id} =========> Returns the status of this studentEnrollment process and should contain the information on the student or any other entities / artifacts of interest. GET: /students/{id} =========> Returns the information on this student, and if the above operation has completed, would have the details on this new enrollment as well. POST: /studentsEnrollment/ =========> response is a 201 with the the "Location" pointing to the id of this process |
and so on.
Among the many questions, one could be:
Q: Why do we have “/studentsEnrollment” instead of “/students/enrollment”?
A. “/students” is being taken as a collection and “/students/{student_id}” make more sense than a business process suffix as in “/students/enrollment”.
References:
Architectural Styles and the Design of Network-based Software Architectures
