RESTful resources: Plural vs. singular when a resource is always singular in the database

Question

If I decide to go with plural for all of my route names but some of the resources only exist as one thing, do you keep it as singular (more intuitive) or respect that decision of using plurals and stay that way?

We were designing a new API for our customer portal in PHP and we had something like this come up:

/api/orders/or-a41931-0001/special-agreement/

And an order can only have one special agreement (and no other types of agreements btw so I can't do /agreements/?type=special or something like that).

is it typical to do /special-agreements/ or is /special-agreement/ used if an order must have exactly one?

Answer 1

More of an opinion based question but...

As far as I see, there are two main types of resources: collection and instance.

A collection would be "users". You can access /users to get the list of users, or access /users/id to get a specific user. The specific user would usually be the instance.

In this case, the reason for the plurality of users is because it is a collection. It makes no sense to use /users if there is no potential to go further (accessing an instance of the collection).

If you were accessing your own profile, you only have one profile, so you should be accessing it at /profile, not /profiles (instance not collection)

In your case, there is only one agreement, so it is not collection, does not require an agreement ID to access it, and therefore should not be plural.