How to (and how not to) design REST APIs

Re:How to (and how not to) design REST APIs by pavlov on Wednesday November 01, 2023 @05:12PM (#38105349)

Does “GET /students” return all the students in the system? Probably not.

So in fact you’re fetching some subset of students anyway, and the size of the returned set might be one or zero depending on your query.

Given that, “GET /student” seems just as meaningful because neither the singular nor the plural can fix the ambiguity about what you’re actually getting.

[ Parent | on HN ]

Re:How to (and how not to) design REST APIs by stickfigure on Wednesday November 01, 2023 @05:23PM (#38105517)

Yes, I would expect GET /students to return all of the students (or at least, all of the students visible to me). Typically with query parameters for filtering:

    GET /students?min_age=20

Alternatively, `students` might be a collection attribute on another resource:

    GET /classes/{class_id}/students

[ Parent | on HN ]

Re:How to (and how not to) design REST APIs by zdragnar on Wednesday November 01, 2023 @06:12PM (#38106054)

I expect singular to return one, and plural to return a set, which could range from 0...n.

Likewise, I wouldn't expect a singular to return a single object wrapped in an array, but I would always expect "/plural" (with no further qualifier in the url) to return an array, regardless of 0, 1 or more results.

Why would returning a full set be a condition of whether or not plural is ambiguous?

[ Parent | on HN ]