CODEWITHSUNDEEP
rest
Sparked
Sparked

Reputation: 874

REST API - Resources That Join Other Resources / Mapping Resources

Assuming I want to stay close to REST principles, if I have a resource named students and a resource named courses, I could book someone on a course like this:

PUT: api/courses/{courseId}/students/{studentId}

Instinctively, I would like to list the student bookings like this:

GET: api/courses/{courseId}/students

But I would like to include some information relevant to the booking (like booking number), meaning a third mapped resource.

So, I'm proposing that to get the student bookings, we would need a separate booking resource, that might look like this:

GET: api/courses/{courseId}/student-bookings

My question: Does anyone see a problem with the above approach, since the endpoint I'm using to create the booking is different to the endpoint I use to retrieve the booking that has been created?

edit: Another alternative, which feels better to me would be the below, although it doesn't really change the question, which pertains to accessing a created resource using a different endpoint to the one that created it:

GET: api/courses/student-bookings?courseId={courseId}

Upvotes: 1

Views: 754

Answers (1)

cassiomolin
cassiomolin

Reputation: 130947

Assuming I want to stay close to REST principles [...]

REST doesn't care about the URI design. But using a URI that properly identifies your resources and allows your API to evolve is considered a good practice.

I understand the booking (or enrollment) as a new resource with it's own attributes.

So, besides /api/courses and /api/students, I would have /api/enrollments, that maps to the relationship between a course and a student.

An enrollment could be created with a POST request, as shown below:

POST /api/enrollments HTTP/1.1
Host: example.org
Content-Type: application/json

{
  "course": "designing-wep-apis",
  "student": "john.doe"
}

A successful request would return 201 and the Location of the enrollment that has been created:

HTTP/1.1 201 Created
Location: /api/enrollments/20180012

The following request can be used to retrieve all enrollments of particular course:

GET /api/enrollments?course=designing-wep-apis HTTP/1.1
Host: example.org
Accept: application/json

And the following to retrive all enrollments of particular student:

GET /api/enrollments?student=john.doe HTTP/1.1
Host: example.org
Accept: application/json

Upvotes: 4

Related Questions