Search code examples
restnaming-conventionsendpoint

REST API Endpoint naming for specific sub-categories of data

Say I have an API that (along with other entities) deals with tasks. My endpoints would look something like

GET /api/tasks //List all tasks
POST /api/tasks //Create a new task

GET /api/task/1 //Fetch a single task
PUT /api/task/1 //Update a single Tasks

GET /api/task/1/comments //Get the comments of task 1

I also need a few subsets of Task data which has an entirely different formats:

  • user-tasks, tasks for a user but shaped according to schedule.
  • sync-data, all tasks that need to be sent to an external system with special references

I can see the user data could exist off the user hierarchy such as

GET /api/user/1/tasks //tasks for this user with dedicated

But what of sync-data? Should this fall under the tasks heirarchy or under the system it's intended for such as

GET /api/ExternalSystemA/tasks //tasks for synchronization
Solution

  • REST doesn't care what spelling conventions you use for your URI. Any spellings that are consistent with the production rules in RFC 3986 are fine.

    Relative resolution provides a standardized mechanism for computing a new URI from a context and a relative reference. Designing your hierarchy so that you can take advantage of that is, in some cases, a really good idea.

    Otherwise, it is a lot like choosing a variable name - the machine doesn't care, so you just want to choose spellings that are satisfactory for other human beings; in other words, making sure that you are consistent with local conventions.