Let's Build an API together - Part 4

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

Now that we have settled on using REST, we face the next decision with naming our endpoints. It seems easy, but I’ve found three way so far, and I believe all claim to be best practice. Which I find funny.

However, what they have in common is, that you should name the endpoints after your entities and not with some arbitrary method names like getTasks.

Names like getTasks, changeTask or alike are not good for REST API as each instance of our object (task) will get its own endpoint, you would end up with paths like getTask/4711. It does not clearly identify the entity we retrieve. Nonetheless, you can use other namings in non REST context if it fits your particular context.

Let’s see how the three approaches differ:

1. Entity name in singular regardless if you receive a collection or a single instance, i.e., /task/4711 or /task
2. Entity name in plural ignoring any grammar by just appending an s, i.e., /tasks/4711 or /tasks
3. A mix of 1 and 2. Collections use plural ignoring grammar and single entities in singular, i.e. /task/4711 or /tasks

What I find interesting here is the paradigm shift from former table naming in SQL. There good practice was to use singular naming, i.e. task.

Choose what makes sense for you and your particular context. Although stick to ONE naming scheme in your whole application or applications if your team maintains more that one. If not, it will confuse you like hell.