Let's Build an API Together - Part 20

Last Update: 24.01.2018. By Jens in API Series | APIs | Newsletter

Before we implement any security, let’s step back and add multiple kanban boards for a user.

For that, we will refactor the API like:

• /boards - GET a list of boards and create a new one with POST
• /tasks/{BoardId} - same as before but we limit the tasks per board, POST adds a new task in the given board
• /task/{TaskId} - GET, DELETE, PUT a single task

Right now, I do not intend to let boards change, but if we offered it, it would be under /board/{id}/.

However, the interesting part is, why did I choose /tasks/{BoardId} over one like /board/{BoardId}/tasks. Both are valid approaches. It depends on the use case and how we use each part. Also, consistencies play a role - being consistent with naming throughout an API is essential. If I name the endpoint /board/{BoardId}/tasks, the one for working with a single task should be /board/{BoardId}/task/{taskId}. So in order, to work with a single task, I would also need the board id and always include it in the URL. Do we really have to know the board when we change a single task? No.

When we request tasks, we are probably getting tasks for a specific board. I can’t imagine a use case for the API where we load tasks independently of a board. That’s why I made it a URI parameter and not just a query parameter. Being in the URI makes it clear, that it is required all the time.

It also helps in keeping the path short and understandable.

But that doesn’t mean the nested approach is bad. There might be cases where it is the better fit.