0

I have 2 UI screens. the first UI screen only displays high level summary such as class, number of students in class.

i have details screen that displays the more information such as class, number of students, students information in class etc.

what is the best practice to design such API for consumption via UI - can I call it as /summary, /details API ? or follow REST convention and call it as /class ( GET class details ) and pass appropriate filters to receive summary vs details i.e /class?filter=summary|details

please advise.

user476566
  • 1,319
  • 3
  • 26
  • 42

2 Answers2

0

Both approaches are fine as REST endpoints.

Yes, it's typical to have fine-grained resources that describe specific things, but it's also acceptable to create custom endpoints that optimize for very specific use-cases.

In fact, a single endpoint that has all the relevant state and describes all possible actions a user can perform from that state might be considered more RESTful if you follow the original academic idea of REST vs the common understanding of what REST is.

From a pure architectural standpoint it could be a higher risk if you have many specialized endpoints vs a few general ones. Could potentially result in a higher frequency of API changes and more code could mean more risk. Your mileage may vary.

Tl;dr: either is probably fine and have a cost/benefit.

Evert
  • 93,428
  • 18
  • 118
  • 189
0

I would prefer the second approach as it is more ressource oriented (best practice) while path segments like "summary" indicate a way of representation.

For me the main goal of designing APIs is to improve the developer experience and to make it intuitive to use. That's why I think the best is to align your API design with your use case by default.

Example:

  • If you want to have a summary page showing all classes, you can include some high-level information into your /classes endpoint by default.
  • If your detail page only shows detailed information for one class you could by default serve more detailed information on your /classes/123 endpoint.
  • Additionally you could add optional query parameters ?show=details (like you already suggested) to influence the default behaviour.
Philipp
  • 470
  • 2
  • 10