Let's Build an API together - Part 3

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

We finished with 4 endpoints and the question if we could use REST for the API last time.

The endpoints were:

• creating a task
• deleting a task
• changing a task aka moving lanes
• list all tasks

To REST or not to REST? That’s a pretty good question. As with strict REST, we had to use HATEOAS. If you are unfamiliar with those, check out this.

For our simple version, it would work. The client has an endpoint for each task and can browse all tasks. As it is a single object right now, we won’t be even bothered by the HATEOAS link to object stuff. However, as soon as we extend the API so that multiple Kanban boards are possible, it makes it harder. If we would follow REST with HATEOAS, a board object will contain only references to the containing tasks with a link. Our client must call these links to actually retrieve the task. So, if we have 10 tasks on the board, we’d be making 11 calls; one for retrieving the tasks on the board and one for each task.

Without REST with HATEOAS, we could do it in one call. Just retrieve the board with all tasks on it. However, HATEOAS might work in your particular version. Evaluate carefully.

I don’t think HATEOAS is a good choice for the Kanban API, so we leave that out. However, the other aspects of REST work fine like each object has its own endpoint. Instead of coming up with an own version, we will stick along REST as long as it fits.

Do we have other solutions? Sure.

• We could use Websockets
• just create 4 endpoints, for each function one. So when deleting and changing a task, we pass its id as a parameter.

Websockets don’t make sense. We don’t need real-time communication. And the other solution is close to the REST-like from above but doesn’t give a benefit over it. Stay close to REST, however, gives us the benfit or using tools in this area like for API docs and testing.