Routing strategy for a restful service

Question

We're working on a restservice using Web-API and breaking our heads on what routing strategy to follow.

We got some resources:

• Grades
• Messages
• Homework

(As a side note: We plan on using Hateoas to have linking between resources. )

We're considering Controller[Action][Id] resulting in

API\Grade[?personid] (GET/POST)

API\Grade\{id}[?personid] (GET/PUT/DELETE)

API\Grade\Lastgrades\{days}[?personid] (GET) 

Or using a context

API\Student\Grade (GET)

API\Student\Grade\{id} (GET)

API\Student\Grade\Lastgrades\{days} (GET)

AND

API\Parent\Student\{id}\Grade (GET)

API\Parent\Student\{id}\Grade\{id} (GET)

API\Parent\Student\{id}\Grade\Lastgrades\{days} (GET)

AND

API\Teacher\Student\{id}\Grade (GET/POST)

API\Teacher\Student\{id}\Grade\{id} (GET/PUT/DELETE)

API\Teacher\Student\{id}\Grade\Lastgrades\{days} (GET)

Is there a good reason to use one strategy over the other?

Answer 1

In your 1st option, the focus is on grades, which is the resource that the API is designed to manage.
In your 2nd option, by just looking at the URL patterns, there are few more resources involved, like Teachers and Students.

Without really knowing your business use-cases, the answer to your question is more have do with the initial scope of your API . If it is focusing on Grades but not Teachers nor Students, then you can just provide API to manage the ‘grades’ resources, meaning your option-1.

Later if you need to also manage “Teachers and Students”, you can add the options-2 to your implementation.

They don’t necessary to be mutually exclusive.

Update-1

The role/context should not be part of the URL. It should be handled separately like once each role is logged into the system; there should be already ways to associate with the role in the backend for example via session etc.

The URL design focus should be on the resources, in this case the Grades. Also since logically, Grades should be associated with Students or even associated with a class that a student took, I will suggest designing it like in the following

/api/v1/grades/students/[student-id]/

OR

/api/v1/students/[student-id]/grades/

OR

/api/v1/students/[student-id]/classes/[class-id]/grades/

These are all acceptable solutions and depending on your business use-cases, one may be better than other.

The roles only come to play as what CRUD operations can act on these resources, like Teacher can POST/PUT/GET on

/api/v1/students/[student-id]/grades/

But Students/Parents can only do GET on

/api/v1/students/[student-id]/grades/

You still need to consider the role/context as part of your overall design and perhaps how the URL design may make more sense depending on how you want to support the operations that each role will use the URL to manage the resources. But the 'context/role' should not be part of the URL.