What is the best practice for API endpoints?

by Dabbas   Last Updated February 13, 2018 14:05 PM

I don't know if the title is reflecting the question correctly, but I can explain more than write a good title.

If I have a system that has (employees, departments, orders, etc...), and have many ways to call the endpoints of this system, and each way requests data less or more of the same entity (e.g employee entity), let's say I'm building the employees endpoints:

  • I need an endpoint to show all employees for managing purposes.
  • I need one to be used in dropdowns on UI to choose one employee (for some reason), and only should show IsActive = true employees.
  • I need one because in one page for a specific role he should be able to see only his employees not all of them (and at the other hand another role allowed to see all the employees).

This kind of requirements is normal and repeated in a lot of systems, but I'm lost and need to know when to put the filters and is it ok to use one endpoint and provide many filters for it (like one for getting only { id, name } but with filter to be able to get only IsActive = true or all employees), or should I separate the endpoints ? and depending on what exactly ?

I know I can use GraphQL or OData and it'll ease the things for me and for consumers of my API, is it the only solution ?

Tags : rest api-design

Related Questions

Including aggregate data in REST response in DDD

Updated February 16, 2018 11:05 AM