Re:How to (and how not to) design REST APIs
by rswail on Thursday November 02, 2023 @01:53AM
(#38109470)
I use Nouns exclusively in APIs, not verbs. URLs define resources. Resources are (99% of the time) Nouns.
So POST /students/{id}/enrollment
Or POST /students is the act of enrolling a student, so the returned Location might be /students/{id}/enrollment to reflect the current state of that resource.
The other details of the student might be at URLs like /students/{id}/details, /students/{id}/results, /students/{id}/courses etc etc
If I end up having part of a "sub-resource" in the "main" resource, then I try to always have an href, otherwise you have to put all of the information.
So GET /students/{id} might return a JSON object with an embedded "enrollment" object, but that embedded object would have an href to the full enrollment resource.
So POST /students/{id}/enrollment
Or POST /students is the act of enrolling a student, so the returned Location might be /students/{id}/enrollment to reflect the current state of that resource.
The other details of the student might be at URLs like /students/{id}/details, /students/{id}/results, /students/{id}/courses etc etc
If I end up having part of a "sub-resource" in the "main" resource, then I try to always have an href, otherwise you have to put all of the information.
So GET /students/{id} might return a JSON object with an embedded "enrollment" object, but that embedded object would have an href to the full enrollment resource.