1
00:00:00,150 --> 00:00:03,150
Lecturer: One of the dilemmas when designing REST API

2
00:00:03,150 --> 00:00:06,540
is the singular versus plural dilemma.

3
00:00:06,540 --> 00:00:07,593
Let's explain it.

4
00:00:08,460 --> 00:00:10,436
Let's look at this API.

5
00:00:10,436 --> 00:00:12,210
In this API, which is quite basic

6
00:00:12,210 --> 00:00:15,840
and we discussed a lot of examples that looked like this.

7
00:00:15,840 --> 00:00:19,500
We ask the server to retrieve a specific order,

8
00:00:19,500 --> 00:00:20,733
order number 17.

9
00:00:22,050 --> 00:00:25,980
Now look closely at the entity part of this url,

10
00:00:25,980 --> 00:00:27,420
the order.

11
00:00:27,420 --> 00:00:29,640
Should it look like this

12
00:00:29,640 --> 00:00:33,930
or maybe like this, plural.

13
00:00:33,930 --> 00:00:37,653
So should it be order or orders?

14
00:00:38,670 --> 00:00:41,190
Now, if you think that the answer is clear

15
00:00:41,190 --> 00:00:45,090
and of course we need to use the word order singular,

16
00:00:45,090 --> 00:00:47,910
because we retrieve a single order,

17
00:00:47,910 --> 00:00:50,730
then look at this,

18
00:00:50,730 --> 00:00:53,373
another side of the exact same dilemma.

19
00:00:54,210 --> 00:00:55,620
Look at this API.

20
00:00:55,620 --> 00:00:59,370
So in this API we don't specify the ID parameter.

21
00:00:59,370 --> 00:01:01,920
We have the entity, which is order,

22
00:01:01,920 --> 00:01:06,840
and we add query parameter for a user named John.

23
00:01:07,860 --> 00:01:09,840
So what would it be this time?

24
00:01:09,840 --> 00:01:13,140
Should it be order or orders?

25
00:01:13,140 --> 00:01:15,690
Now, this is more interesting,

26
00:01:15,690 --> 00:01:17,700
because when using query parameters,

27
00:01:17,700 --> 00:01:20,640
we said that the server, the API,

28
00:01:20,640 --> 00:01:23,490
can return more than one entity.

29
00:01:23,490 --> 00:01:27,570
So are we looking for an order or for orders?

30
00:01:27,570 --> 00:01:31,170
Is it a singular action or a plural?

31
00:01:31,170 --> 00:01:34,440
So unfortunately there is no concrete answer

32
00:01:34,440 --> 00:01:35,670
for this dilemma,

33
00:01:35,670 --> 00:01:37,980
and you can find many opinions

34
00:01:37,980 --> 00:01:40,380
on the internet about this.

35
00:01:40,380 --> 00:01:43,050
My recommended best practice is this:

36
00:01:43,050 --> 00:01:46,830
always prefer readability and ease of use.

37
00:01:46,830 --> 00:01:50,190
So always try to build a url and API,

38
00:01:50,190 --> 00:01:52,080
that a developer will look at it

39
00:01:52,080 --> 00:01:56,040
and understand exactly what is going to get back.

40
00:01:56,040 --> 00:02:00,990
So, when the API should return only a single entity,

41
00:02:00,990 --> 00:02:04,200
use order, singular.

42
00:02:04,200 --> 00:02:09,199
But, when the API might return more than one entity,

43
00:02:09,419 --> 00:02:12,003
then use the plural form, orders.

44
00:02:13,200 --> 00:02:16,020
So this is my personal best practice

45
00:02:16,020 --> 00:02:17,520
and you are free to use it.

46
00:02:17,520 --> 00:02:20,973
But again, there is no concrete answer for this dilemma.