Sorry for not replying, I have not received or seen any notifications from this thread.

Thank you for your detailed input, @martinbean

As to my use of the term singleton, let me try to explain myself a bit better than in my previous post. I am aware of the single design pattern, but that was not what I was referring to. I was referring to the mathematical concept of a singleton (sometimes also called a unit set).

Within category theory this is very useful as the mathematical definition of a singleton is a set with the cardinality (number of elements) of only one, and always only one. And the topic I tried to think aloud about in my original post was the category theory that is REST.

Still using mathematical terms a set would be a collection of elements where the elements are distinguishable from each other. Using the REST approach, say we have a route called /blog-posts. A GET request to this route could return a set of all blog posts.

We could represent this using this notation (where B is blog posts and i is its unique ID):

B = {i, ...}

This set notation tells us that a any set of blog posts consists of 1 or infinity number for distinct blog posts. For the purpose of simplicity I had left out the possibility of the state where there are zero posts, which could perfectly well be the case at any given time of course.

This approach is extremely well suited for REST and working with the target's representational state.

A call to /blog-posts/99 also makes perfect sense because we know that it is a reference to a single, distinct item in the set.

However, the thing that gives of a bit a smell to me is when REST is used to refer to a singleton (as in a mathematical singleton).

The definition of a set that is a singleton is if, and only if, it has the cardinality of one. In a software application I can think of several cases where they would appear, especially if we factor in that the routes an end-user and an admin might have very different levels of utility value respectively. The route /users yielding a list of all users could be very useful for an administrator, but might not even be accessible to the end-user. In these cases the cardinality will always be one, ergo they will always be singletons.

Then what is it I am going on about then? Most best practices on how to apply REST to your API tells you to use a plural form for the resource name. See for instance REST API Naming Conventions and Best Practices Well, then let's examine the example of the concept of a user profile. To an admin it could make sense to view the metadata that makes up a single user profile, and that might be achieved with the route /users/1 to get the data for the user with the distinct ID of 1. Same as for the blog posts example above the distinct value 1 would refer to a distinct user within the users set:

USERS = {1, ...}

The route for the end user to access his profile (the meta data that is the profile) could for simplicity be named /profile, but this would be impossible to achieve statelessly. There is no way of distinguishing between different user profiles solely based on the URI.

We could use the route /users/1 or even /users/profiles/1

But to the end user the concept of a set collection of more than one user profile does not make sense. The user is by itself a single distinct item and has a 1-to-1 relationship with the profile. For user 1 to increment URI /user/1 to user/2 would only make sense if the user was trying to illegally access another user's profile.

The notation of the singleton concept of a user profile could be: P = {n+1} using the set theoretic definition of natural numbers. A user profile will therefore always have the cardinality of one.

Just as /users in admin land makes sense and can be represented as U = {0, ...} , /users in end user land would probably be an illegal route endpoint. But this logic seem to be tossed overboard when a single item from the set collection is to be returned. The admin accesses a single user by using the route /users/1 and so also does the end user and framework logic would prevent the user from accessing other user's profiles.

And this is what grinds my gears. The resources in REST are not supposed to be mapped to an entity but a set of entities. The resource invoices could have the URI /invoices and would map to a set collection of 0,1 or an infinite number of invoices. This logic breaks when the set collection is a singleton because it does not make sense to refer to a singleton by a distinct identity because there is only one of it. Using an id implies that it is not in fact a singleton.

Does it really matter?

Seeing that designing routes in a web application is based on very loose rules, it probably does not matter at all. But one of the objectives behind designing RESTful API's is to improve overall quality by being consistent. To me, just ignoring a logical flaw and hack around it is far from trying to be consistent. It at least gives off a smell that should be considered doing something about.

Huge disclaimer

I am in absolutely no way a mathematician nor a computer scientist, so I might very well have these concepts and ideas wrong. Feel free to correct me if needed.