REST API URI Design Approach

Question

I'm working on my first RESTful API design for a greenfield application I'm building and could do with some pointers on the URI's of the API.

For background the system is used by clinicians to get alerts about their patients, so I'll be creating screens that will display a list of alerts that belong to all patients assigned to a clinician.

The clinician will will able to view the alerts by patient name or by alert type.

My first thought was to keep it real simple with URI's as follows:

/api/alerts - gets the full list of alerts
/api/alerts/123 - gets the details of the specified alert
/api/alerts?user=mike - gets list of alerts by user
/api/alerts?user=mike&groupby=patients - get list of alerts by user and group by patient

But I've started having second thoughts and started thinking about it from the users perspective and how to show the relationships better, leading me to:

/api/users - gets the full list of users
/api/users/mike - gets details of specified user
/api/users/mike/patients - gets details of all of specified users patients
/api/users/mike/patients/alerts - gets all alerts for users patients
/api/users/mike/patients/123/alerts - gets all alerts for specified users patient
/api/users/mike/patients/alerts?groupby=type - get all alerts for users patients and group by alert type.

So any ideas, opinions if I'm on the right track.

Should I go with one approach over the other or even use them both?

Cheers, Mike

Answer 1

When designing REST APIs, you are focusing on the resources and from what I can tell, your resources are ‘alerts’, which are the ‘things’ that your API is for. Thus, your approach one make more sense to me.