REST and API naming

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:

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

Rest API Design – Resource Modeling

Leave a Reply

Your email address will not be published. Required fields are marked *

     

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">