Represent nested resources that has two different type (entites) owners in REST APIs?

Question

Suppose I have a entity called Appointment. This entity represents an medical appointment between one Doctor and one Patient.

To create a new Appointment, I send somethind like:

POST /appointments

{
 "doctorId": 98173821,
 "patientId": 2138212,
 ... omitted for brevity
}

Works well.

As you can see, this object is nested with two other resources (Patient and Doctor)

Imagine that logged Patient (using his JWT Token) want to see his history of Appointments.

Today, I do that sending a request to:

GET /patients/2138212/appointments?page=1&size=2&startDate=2019年01月01日&endDate=2019年08月01日

(please, feel free to criticize)

as this is a history, there's no need to retrieve the whole Appointment objects. The response retrieves only basic informations about the Appointments. The response looks like this:

{
 "timestamp": 1566216359,
 "transactionId": "6eed92831cad128",
 "data": {
 "appointments": [
 {
 "id": 6372,
 "doctorId": 98173821,
 "date": "2019-01-01"
 },
 {
 "id": 6985,
 "doctorId": 98173821,
 "date": "2019-02-01"
 }
 ]
 }
}

Now, what if the Patient select an specific Appointment in the front-end and the detailed information about this specific Appointment needs to be shown? What is the best way to model a REST endpoint like this?

My options:

• GET /patients/2138212/appointments/6372
• GET /appointments/6372

The first one looks nice and follow up REST patterns on nested resources, since can represent that the Appointment 6372 belongs to the Patient 2138212.

The second one doesn't provide readability. I mean, looking at the resource, I don't know who owns this Appointment. That's why I prefer the first approach.

Now, going down the road, also, the Doctor has to see the history of his Appointments.

Today, I do that sending a request to:

GET /doctors/98173821/appointments?page=1&size=2&startDate=2019年01月01日&endDate=2019年08月01日

(please, feel free to criticize)

The response looks like this:

{
 "timestamp": 1566216359,
 "transactionId": "6eed92831cad321",
 "data": {
 "appointments": [
 {
 "id": 6372,
 "patientId": 2138212,
 "date": "2019-01-01"
 },
 {
 "id": 6985,
 "patientId": 2138212,
 "date": "2019-02-01"
 }
 ]
 }
}

Now, what if the Doctor select an specific Appointment in the front-end and the detailed information about this specific Appointment needs to be shown? What is the best way to model a REST endpoint like this?

My options:

• GET /doctors/98173821/appointments/6372
• GET /appointments/6372

The questions I have:

1. How to represent a nested resource that has "two owners"? There is a better approach than this I point out on that question?
2. To the history of Appointments, I've been suggested to do /appointments/doctors/{doctorId} and /appointments/patients/{patientId}, which I heavily disagree, since the Doctor and the Patient owns the Appointment, not the opposite. What you suggest?

Answer 1

You can have

• GET /appointments/6372

as canonical url for appointment 6372

and two non canonical urls:

• GET /patients/2138212/appointments/6372
• GET /doctors/98173821/appointments/6372

non cannonical urls would add Link header with rel="cannonical" link to canonical url