Should I use Singular or Plural name convention for REST resources?

Question

I'm new to REST and I've observed that in some RESTful services they use different resource URI for update/get/delete and Create. Such as

• Create - using /resources with POST method (observe plural) at some places using /resource (singular)
• Update - using /resource/123 with PUT method
• Get - Using /resource/123 with GET method

I'm little bit confused about this URI naming convention. What should we use plural or singular for resource creation? What should be the criteria while deciding that?

Solution 1

The premise of using /resources is that it is representing "all" resources. If you do a GET /resources, you will likely return the entire collection. By POSTing to /resources, you are adding to the collection.

However, the individual resources are available at /resource. If you do a GET /resource, you will likely error, as this request doesn't make any sense, whereas /resource/123 makes perfect sense.

Using /resource instead of /resources is similar to how you would do this if you were working with, say, a file system and a collection of files and /resource is the "directory" with the individual 123, 456 files in it.

Neither way is right or wrong, go with what you like best.

Solution 2

For me is better to have a schema that you can map directly to code (easy to automate), mainly because code is what is going to be at both ends.

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

Solution 3

I don't see the point in doing this either and I think it is not the best URI design. As a user of a RESTful service I'd expect the list resource to have the same name no matter whether I access the list or specific resource 'in' the list. You should use the same identifiers no matter whether you want use the list resource or a specific resource.

Solution 4

Plural

• Simple - all urls start with the same prefix
• Logical - orders/ gets an index list of orders.
• Standard - Most widely adopted standard followed by the overwhelming majority of public and private APIs.

For example:

GET /resources - returns a list of resource items

POST /resources - creates one or many resource items

PUT /resources - updates one or many resource items

PATCH /resources - partially updates one or many resource items

DELETE /resources - deletes all resource items

And for single resource items:

GET /resources/:id - returns a specific resource item based on :id parameter

POST /resources/:id - creates one resource item with specified id (requires validation)

PUT /resources/:id - updates a specific resource item

PATCH /resources/:id - partially updates a specific resource item

DELETE /resources/:id - deletes a specific resource item

To the advocates of singular, think of it this way: Would you ask a someone for an order and expect one thing, or a list of things? So why would you expect a service to return a list of things when you type /order?

Solution 5

Singular

Convenience Things can have irregular plural names. Sometimes they don't have one. But Singular names are always there.

e.g. CustomerAddress over CustomerAddresses

Consider this related resource.

This /order/12/orderdetail/12 is more readable and logical than /orders/12/orderdetails/4.

Database Tables

A resource represents an entity like a database table. It should have a logical singular name. Here's the answer over table names.

Class Mapping

Classes are always singular. ORM tools generate tables with the same names as class names. As more and more tools are being used, singular names are becoming a standard.

Read more about A REST API Developer's Dilemma

For things without singular names

In the case of trousers and sunglasses, they don't seem to have a singular counterpart. They are commonly known and they appear to be singular by use. Like a pair of shoes. Think about naming the class file Shoe or Shoes. Here these names must be considered as a singular entity by their use. You don't see anyone buying a single shoe to have the URL as

/shoe/23

We have to see Shoes as a singular entity.

Reference: Top 6 REST Naming Best Practices

View more solutions

Comments

[Dmitry Gonchar]

Great answer! But "default" directories in Windows have plural names. Like "Program Files", "Users", "Documents", "Videos" etc. Also I have encountered plural names in website urls much more often.

[Warren Rumak]

This is the best answer as far as I'm concerned. I appreciate that API designers like the linguistic correctness of saying "get resource #123", but it's extra coding hassle when writing clients of the API as well as help documentation. (GET /api/people vs. GET /api/person/123? euuuchh.) .... instead of thinking of it like "get resource #123", phrase it in your head like "get from the collection of resources that matches #123".

[FlavorScape]

Das Auto is way better than Die Autos. Also, English plural conventions are not consistent.

[arpadf]

The resource namespace is a matter of semantics, not implementation. So, using the DB tables analogy, is not very fortunate. Also when working with DB-s you are manipulating only tables, though of course you can affect the content (rows), but in REST there is no constraint to manipulate a single resource directly.

[Tomasz Pluskiewicz]

@WarrenRumak actually there should be no hassle if APIs were hypermedia-driven. Alas, most aren't. Anyway, in such case naming would be of secondary importance during implementation

[Erik]

Distinguishing plural/singular resources is not about linguistic correctness but about scale. /employees/12 reads to me as the subset of the employees resource with id '12' (it could mean anything, for instance a saved search query on recently fired employees). If you read the above as the employee with id '12', how would you represent the subset? The only option is by making URI's more complex ore distinguishing collections containing objects from the objects themselves (i.e. singular vs plural).

[Jan Deinhard]

Choosing /employees/12 to represent a search query on recently fired employees (or any subset) would be bad design I think. If you want to represent subsets of any kind than I suggest to introduce them as resources (with proper names) in their own right.

[Todd Menier]

I think this is a good analogy, but more important than deciding whether to go singular or plural is to be consistent with whichever you choose. You're not going to insert into Users and then select from User. Same rule should apply to REST resources - don't rename them depending what you're doing.

[richard]

@WarrenRumak you are thinking in terms for the client building up the urls. If the API is implementing proper HATEOS and the client is consuming it with that expectation, it shouldn't matter whether it's people or person or anything else...the uri is determined by the server.

[richard]

@Erik It's not a good uri because it doesn't properly establish a vector. You are correct...what does 12 represent? Better is to use vectors, i.e. /employee/id/12. Then you can do /employees/fired?top=12 or /employees/hired?top=12 or /employees/hr?top=12 etc. and veer off into any other meaningful (for your domain) set of vectors.

[richard]

The difficulty or ease of this is due to not respecting HATEOS. It shouldn't matter whether it's plural or singular or anything else. You should respect the uri's sent from the server and not "build up" your uri's on the client. Then you have 0 mapping to do for your code.

[Warren Rumak]

It shouldn't matter, @richard, but it -does-, for a variety of reasons. One important one is language itself: It's more challenging for non-native speakers of the language which you specify your REST API in. Japanese, e.g., has no pluralization of nouns, and many nouns have the same word either way (Romanian for both 'name' and 'names' is 'nume'). And what's the plural of acronyms like "BIOS" supposed to be? If your goal is to communicate "many" via a URI, you're going to run into hard failures like this from time to time. The extra complication is best avoided -- it wins you exactly nothing.

[richard]

@WarrenRumak Your comment above says " I appreciate that API designers like the linguistic correctness of saying "get resource #123", but it's extra coding hassle when writing clients of the API as well as help documentation." Your previous point being that while linguistically more correct, it's extra coding hassle etc. But now you say it's more linguistically difficult - which is it? I think being consistent with the language you are writing in is easier for non-native speakers to understand than deviating from the language to compensate non-issues (coding hassle).

[Warren Rumak]

You're having difficulty understanding my position, richard? Okay, I'll try to simplify it for you: It is not 'more consistent', 'easier to program', 'easier to maintain' or 'easier to monitor' a program where you use two different words to represent one type of resource. Consider "person" vs. "people": Whether you're a sysadmin scanning a logfile, a Chinese developer weak with English, or any developer learning your API for the first time, this presents a roadblock that increasing learning time while providing ZERO BENEFIT to the functioning of the app.

[Erik]

This has nothing to do with understandability for the clients. It's about addressing different things with different URLs. And being able to respond to all HTTP methods without being in conflict. You can have a resource that is a collection of items, and a resource that represents an item itself. For all I care the collections resource could be example.org/166316e2-e1and one particular item in that collection example.org/20d68348-ccc-001c4200de. The client should not construct URLs (that obviously doesn't scale, it isn't RESTful and that's what link relation types are for).

[Erik]

If you don't think arbitrary URLs are pretty, feel free to identify a collection resource with a plural name and an individual item with a singular name. If you don't like english URLs and your natural language doesn't support that way of singualr/plural notation use something else to define it in your preferred language I suppose all languages enable you to somehow distinguish '/the-collection-of-bla/2321' versus 'bla/61' in writing. And each of those two different resources represent completely different results when sending GET/PUT/DELETE/POST/PATCH and others.

[Admin]

@richard The client still has to do mapping. In HATEOS they would have to map to a name that represents the relationship (rel) to the URI construction. The rel, method (verb) and Content-Type then make up the resource media. This does not preclude the need for a good URI design. Even though the client might give precedence to the rel name the developers of the API still need a good human-readable standard for URI construction.

[PositiveGuy]

the defacto convention pretty much most people and APIs out there take is keeping it plural at all times. Ids specify ONE resource cars/id

[PositiveGuy]

"Neither way is right or wrong, go with what you like best.". Ah the famous line I hear so often and get sick and tired of hearing from people. Conventions matter and SHOULD be debated constructively amongst the community, that's where better solutions come about and good practices. When you are using both plural and singular for resource names in URIs, it complicates your code and the API because the user and the code behind the API has to account for that in routes and logic to differentiate single vs. plural whereas if you just stick with plural all the time you have no problems.

[crush]

Seems like the plural form has been chosen because developers seem to assume that all resources are inherently part of some collection. However, the "accepted convention" seems to indicate that POST /users should create a single user, adding it to the collection. I disagree. POST /users should create a list of users (even if that is a list of 1), where as POST /user should create exactly one user. I see no reason why both plural and singular resource endpoints can't co-exist. They describe different behaviors, and shouldn't surprise anyone of their function.

[Tomasz Pluskiewicz]

@WTF this is completely not true. the URI templates should be completely opaque. Here's a quote from Roy Fielding's dissertation "At no time whatsoever do the server or client software need to know or understand the meaning of a URI". It should not be necessary to construct or deconstruct a URI on clients and servers. A good API should work equally well even with all URLs using GUIDs like http://example.org/{GUID}. This is because URLs should be communicated as links. Client's don't care how server assigns identifiers and server-side routing can be mitigated by using complete URLs as ids

[Travis D]

@TomaszPluskiewicz You are entirely right that clients do not care. As software developers we should care -- and for that I agree with WTF's comment that constructive debates about convention are valuable.

[Tomasz Pluskiewicz]

@TravisD you are right that constructive debate is valuable. but in this case common arguments, such as WTF saying that using both plural and singular for resource names in URIs, complicates your code is out of place. The client should never construct the identifiers thus it is not a good argument

[Gert Arnold]

Singular names are always there /clothe/12/trouser/34 :)

[Eastern Monk]

I would advice that stick to either one of them. Singular plural is something that English-speaking humans can understand easily but it is not trivial for the machine to understand. Is Inventory singular or plural ? Why is User's plural is User+s but for Baby it is Babies? This makes it very inconsistent. for a machine.

[Eastern Monk]

This is a better answer in my opinion. Except that I have always preferred to use Singular instead of plural. User.getList(), User.getById, User.delete etc.

[Ben George]

So can someone just put a one word answer and have it accepted so I don't have to read this all (again).

[Tom Russell]

Nice try. But it would be better as "accessLogEntries". :-)

[Tom Russell]

Isn't there a convention for specifying a resource id in the path? If so, it seems to be widely neglected. For instance, POST users/<id> would create a new user.

[Wirone]

It's not an argument for me since Postman offers collections, so you can save all resources as different collection items and test them individually. All you do is selecting resource from collection, you don't have to edit parameters/methods/etc everytime.

[Carrie Kendall]

@TomRussell why? The implications of this are important. I understand why you would use plural even when you're accessing a resource by an identifier, but for a many-to-one or one-to-one it's quite misleading. Consider an api that manages staff members for a multi-location company. Each staff member works at one location. GET /users/123/location should fetch the location that the user works at. Isn't GET /users/123/locations really misleading as a consumer?

[Sven R. Kunze]

Usually the slash '/' at the end of a URL represents a container. I.e the container /resource/ basically has sub-resources /resource/12 and /resource/23..

[Tom Russell]

@CarrieKendall I see your point. Since accessLog is modeled as an attribute, or value, rather than an entity it should be singular. If you're given to over-engineering, then a log entry would be an entity and you'd have /api/accessLogEntries?resource=123.

[Carrie Kendall]

Agreed, although, I think it does break convention of pluralize all the things. It's a tricky one. To me, it's important than an API be straight-forward ie documentation should compliment an already straight-forward implementation.

[Tom Russell]

I'm more of a programmer than a systems or database person so I like an API that tells a story rather than adheres to convention. The implications for automated documentation are real, though.

[Alex]

@TomRussell usually the server creates the id, so you wouldn't know the id to POST to yet.

[thanos]

I like the simplicity. The mapping also has the benefit of making documentation and tests on routes incredibly easy to write.

[bytedev]

Its not just table names, its also comparable to class names in OO (my class would be called Customer not Customers).

[Steve Buzonas]

@GertArnold the word clothe is a verb. Rest APIs generally stick to nouns when talking about resources and use verbs when describing actions. The singular form is clout, but is archaic and would likely be more suitably replaced by garment.

[Jochem Schulenklopper]

@TomRussell, when the client determines (a kind of) id when creating a new resource, it is more common to use PUT /users/<id> instead of POST. POST has the interpretation "add this to the collection, and determine the id as part of that". PUT has the interpretation "update (or add) this resource with this id." See restcookbook.com/HTTP%20Methods/put-vs-post for a longer explanation of this principle.

[user1428716]

how do you create a url for search on resources .. /resources/search?queryParam

[André C. Andersen]

This makes sense to me. However, we're a database-first shop, meaning we generate code and api entities from our database schema. And database standards tend to advocate singular table names, so we're going with that, but still under the same logic as this answer.

[StriplingWarrior]

This makes sense to me. If you think of the file system/website analogy, plurals represent folder names whereas singular names represent files. A PUT should be used for both creation and updating on the api/resources/123/accessLog endpoint: since there's no need for an ID or a new URL to represent the accessLog after it's created, a POST doesn't make sense there.

[Cattani Simone]

In this case, semantic is too much important to simply accept "already defined" trends

[gimbel0893]

I believe you should be using plural when referring to a single item. Maybe both are accepted as REST best practices but plural is more common. GET /resources (list of all of them) GET /resources/{id} (a single resource)

[João dos Reis]

Shouldn't this be split is /cart and /cart/item(s) anyway? Then you can address the whole cart (e.g. with a delete) or individual items?

[user2864740]

@RobertGrant Wouldn't that be "/carts/items/123"? (eg. why "cart" and not "carts" is the rule is 'always plural'?)

[user2864740]

This addresses code that tries to "auto generate/mangle" endpoints (there are many opinionated libraries that assume plurality/singularity and attempt to map); however, this does to apply to explicitly chosen endpoint names any more than the picking the right word (regardless of how it's pluralized).

[Andrew T Finnell]

POST /customer sounds like it's going to replace the one and only customer. This is my biggest grief with using singular resource names.

[Andrew T Finnell]

I'd argue that if production code is checked in that is able to perform a delete of everyone's cart items there are bigger issues than the naming convention. The likely hood they 'd remember an 's' over an ID is much less.

[Andrew T Finnell]

Why are you mixing idioms here? You use the proper URI notation in the first paragraph and then switch to query parameters? Using query parameters to obtain a resource with an ID of 123 is wholly off base here.

[pberggreen]

That was clearly a mistake. I have updated my answer now. Thanks for noticing it.

[wynnset]

If you are doing 302 redirects and your cache is storing everything twice, you have set up your cache wrong. Cache is not supposed to store 302 redirects.

[maaartinus]

If you client always uses /resources and always get redirected to /resource, you've done it wrong. If someone else uses your API, they can either use the correct URL directly or be redirected (which works but is wrong) and it was you who opened the wrong way.

[Kamil Kiełczewski]

Singular: In case, when part of your system is only one object (0-1, exists or not) e.g. users/1/avatar you can use singular form for label this single object (e.g. avatar) - more detailed example here: stackoverflow.com/a/38296217/860099 . BTW - very nice answer :)

[wynnset]

Not sure by what you mean "wrong" - that's very subjective. It's not really wrong because it does work.

[pberggreen]

After being downvoted again, I looked at what I wrote and I realized that the original post was correct. My point was exactly that if the user does the wrong thing, then using plural+singular will in fact give a better error message that using plural only.

[Andrew T Finnell]

I still feel this is confusing the issue at hand. The idea of using plural is that it’s a collection. And the number on the end is an index into the collection. What if you GET /resource by itself? Using both plural and singular together is quite confusing. Saying /resources/123 says: Get my resource 123 in the resources bucket.

[Will Sheppard]

What about mapping to class and table names, which should be singular? (see other answer)

[Will Sheppard]

This increases the maintenance cost, and the cost of understanding, and the amount of code required.

[Eric Knudtson]

@WillSheppard - Class names are best in singular form and table names are best in plural form. For example Order is a good name for a class that deals with singular instances of objects referring to one order. OrderList is a name for a class that deals with multiple Order instances. Orders Table is a good name for a database table of many orders.

[jim smith]

I want to GET /orders but I only want /1

[Goldfish]

I disagree with having different URLs for a single GET vs GET list. This means users need to manage additional URL's depending on their method. Keep it all the same for the best ease of use

[kishor borate]

I don't understand the concern here. We are not supposed to change singular to plural programatically. Most of above plural forms are well known, and should not be a concern. If someone has poor English knowledge, he is going to spell any part of your variable incorrectly. Also, going by your logic, do you also recommend using singular forms to refer collections in source code as well?

[donmutti]

@andrew-t-finnell Isn't POST /customer supposed to do the very thing - insert a single customer?

[Andrew T Finnell]

It inserts a single Customer into a collection of Customers. POST /customer reads to me as though it is POST'ing to the customer. Not a collection of Customers. However, I'll admit that Plural or not Plural is a preference. As long as they aren't mixed like the other Answer has. That would be incredibly confusing.

[Andrew T Finnell]

I don't believe the comparison to Twitters API is fair as they use the Plural form for all their endpoints. They do not mix Plural and Singular for the same Elements.

[cosbor11]

@AndrewTFinnell - thats the point I was mentioning about twitter

[Josh Woodcock]

we are node developers. we are smarter than database admins :-D

[DaBlick]

Sorry but I voted this down because it violates REST best practices to have two independent URLs that can refer to the same resource. /resource/x and /resources can BOTH include the /resource/x but are independent URLs. Consider a caching system that sees GET /resources, then PUT /resource/x, then GET /resources again. It would be valid for the caching system to presume that a PUT to anything under /resource doesn't affect anything in /resources and thus provided a cached response of the first GET for the second one.

[cosbor11]

@DaBlick - can you site your "best practices" source?

[damd]

There are English words which are irregular to the point where it's often a problem even within the Anglosphere and they're commonly used terms such as index/indexes/indices, vertix/vertixes/vertices, matrix/matrixes/matrices, radius/radiuses/radii, etc. I don't see the point in making REST paths plural anyway, because if they're all consistently singular, it's just more obvious to everyone.

[damd]

"POST'ing to the customer" doesn't make sense in this case. POST doesn't replace, it inserts. Maybe if it were POST /customer/1 I could see the dilemma, but even that doesn't make much sense from a REST perspective, because what are you inserting? It would be /customer/1/invoice or /customer/1/receipt, etc.

[Daming Fu]

@kishorborate, Using plural as URI is more error-prone, even for native English speakers. As damd indicates, plurals like index/indexes/indices are introducing more problems. And there are uncountable nouns. Mixing uncountable nouns with plurals is another problem. Why make it harder for programmers to spend more time on these? I suggest using singulars for everything. If there is an /{id}, then the API should return a single record. If there is not an /{id} that follows, then API should return the collection.

[kishor borate]

@DamingFu Singular resource may not always have id associated with it. eg. /user/{id}/nickName By looking at it, it's not clear, whether it will return list of nickNames or single nickName? Hence, APIs are more intuitive when it uses plural forms. Yes, few words will have irregular plural forms. For someone who is reading the plural form, is not an issue. It's issue only when writing the API signature. But frequency of such words is not high, also, finding the plural form of any word is not time consuming. It's trade off we should accept, to make APIs more intuitive.

[cnps]

would anyone ever create an endpoint that simply deletes an entire collection? Seems extremely dangerous to me, and probably also why REST doesn't really support batch deletes. (you'd have to wrap the array into an object). If I absolutely needed an endpoint to delete an entire collection, I would make sure that URI was very very unique, and definitely not similar to POST

[Patrick Younes]

Let's take StackOverflow as a point of reference. The current URL is stackoverflow.com/questions/6845772/title-of-the-question-wi‌​th-hyphens I believe this somewhat elaborates a bit more on the good practices used by tech giants.

[Rohmer]

@jim-smith then why don’t you request /1 from the collection of users with GET /users/1?

[Koray Tugay]

@SteveBuzonas And for trousers and sunglasses?

[Zon]

I was looking for arguments to choose a convention from the two answers. EasternMonk and André C. Andersen voted for this one, actually giving arguments against it. Entities are intended to be named as singulars. But you can't use singular as universal path part, because it is not suitable to GET multiple entities. So Will Hartung 's convention is less controversial.

[Zon]

Everyone does so - is not an argument. I've tried to find convincing arguments in both answers and comments. See - stackoverflow.com/questions/6845772/…

[berimbolo]

In your example what would you expect GET /user/{id}/friend to represent? I like to ensure that if you remove a portion of the URL a resource is still returned, going on your example, I assume (rightly or wrongly) this would return all the friends of user {id} but this contradicts your use of plurals and nouns.

[john16384]

The plural version is in the answer /user/{id}/friends, and which would return all the friends. The singular version /user/{id}/friend would be a bad request 400, just like /user.

[kiedysktos]

@EricKnudtson I completely agree with your answer. But your last example is not perfect, here is another one: if you take a file with label order you may expect multiple ones inside, because you know it's a folder. But still plural wins, even in this case.

[Jon Guiton]

And the contrary /fish/fish{id}. There are also problems when grouping due to the use of mass nouns which can be archaic also : /murders/murder{id}/crow{id}; /gaggles/gaggle{id}/goose{id}. So it is also possible to pluralise a plural. A 'simple standard rule' will never work, there will always be a mismatch between the rule and the 'natural' human expressiveness of language somewhere. The real question is whether to a) accept a clumsy uri design as a de facto standard b) reject a crude and over simplistic 'standard convention'.

[einord]

@Koray Tugay trousers are interesting because they are historically considered a pair (one for each leg), not always necessary connected at the top throughout history. So they are more like socks or shoes that always are a pair.

[AaronLS]

The plural vs singular debate for table names has always been complicated by the fact that a table defines both its schema/structure(implying singular) as well as being the container/collection for the data(implying plural). You don't have this problem in a programming language because the class definition is singular, but a property holding a collection would be plural. Point being, don't even try to apply class naming conventions to table, and in turn don't apply table naming conventions to rest services.

[Ray Foss]

As you'll ultimately end up using OOP classes at some point, validation, linting and auto completion. In OOP you use classes are usually singular Objects, like Bike, User, Car... To make classes match the API name... I use singular. Some languages require a seperate word for plural, it's no different than Child-duren or Child.find() or GET child?q="". You need protections against accidental multi regardless, most endpoints should have multi... using singular doesn't change that. For REST native API's plural seems the standard. If rest is secondary to your application, singular is easier.

[Henno]

Do not use POST /login. Use POST /sessions to add a session to sessions collection (effectively log the user in) and use DELETE /sessions to remove a session from sessions collection (effectively log the user out)

[Andrés Morales]

If the answer points to "natural language" it's partially correct, because POST /orders has no sense to me in another way that "post many orders" (not a single one), POST /order, I think, is the correct way.

[Kamafeather]

@AndrésMorales having only one referenced name is easier for memory. – I think the use case you mean is already covered by PUT /orders/1 (CreateOrderAt & UpdateOrderAt). While we can POST one or more orders to the collection (Add some orders, and return the created indexes).

[TiggerToo]

I think using session for the login POST makes sense, but I don't agree about pluralizing it. Your user/browser combo never has access to more than one session at a time. You have one, and when you're done it gets deleted. There's no piece of code on either the front end or back end that's ever going to refer to multiple sessions for the user. That to me makes it singular.

[Software Engineer]

Singular names are not becoming standard and most of this answer is based on personal preference.