Lecturer: One of the dilemmas when designing REST API
is the singular versus plural dilemma.
Let's explain it.
Let's look at this API.
In this API, which is quite basic
and we discussed a lot of examples that looked like this.
We ask the server to retrieve a specific order,
order number 17.
Now look closely at the entity part of this url,
the order.
Should it look like this
or maybe like this, plural.
So should it be order or orders?
Now, if you think that the answer is clear
and of course we need to use the word order singular,
because we retrieve a single order,
then look at this,
another side of the exact same dilemma.
Look at this API.
So in this API we don't specify the ID parameter.
We have the entity, which is order,
and we add query parameter for a user named John.
So what would it be this time?
Should it be order or orders?
Now, this is more interesting,
because when using query parameters,
we said that the server, the API,
can return more than one entity.
So are we looking for an order or for orders?
Is it a singular action or a plural?
So unfortunately there is no concrete answer
for this dilemma,
and you can find many opinions
on the internet about this.
My recommended best practice is this:
always prefer readability and ease of use.
So always try to build a url and API,
that a developer will look at it
and understand exactly what is going to get back.
So, when the API should return only a single entity,
use order, singular.
But, when the API might return more than one entity,
then use the plural form, orders.
So this is my personal best practice
and you are free to use it.
But again, there is no concrete answer for this dilemma.