REST URI convention - Singular or plural name of resource while creating it

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

User · Answer

See Google s API Design Guide  Resource Names for another take on naming resources  The guide requires collections to be named with plurals   -------------------------- --------------- ------------------- --------------- --------------    API Service Name           Collection ID   Resource ID         Collection ID   Resource ID     -------------------------- --------------- ------------------- --------------- --------------      mail googleapis com       users           name example com    settings        customFrom        storage googleapis com    buckets         bucket-id           objects         object-id      -------------------------- --------------- ------------------- --------------- --------------   It s worthwhile reading if you re thinking about this subject

User · Answer

I am surprised to see that so many people would jump on the plural noun bandwagon  When implementing singular to plural conversions  are you taking care of irregular plural nouns  Do you enjoy pain   See http   web2 uvcs uvic ca elc studyzone 330 grammar irrplu htm  There are many types of irregular plural  but these are the most common   Noun type   Forming the plural  Example  Ends with -fe   Change f to v then Add -s        knife   knives      life   lives      wife   wives Ends with -f    Change f to v then Add -es       half   halves      wolf   wolves     loaf   loaves Ends with -o    Add -es      potato   potatoes     tomato   tomatoes     volcano   volcanoes Ends with -us   Change -us to -i         cactus   cacti     nucleus   nuclei     focus   foci Ends with -is   Change -is to -es        analysis   analyses     crisis   crises     thesis   theses Ends with -on   Change -on to -a         phenomenon   phenomena     criterion   criteria ALL KINDS   Change the vowel or Change the word or Add a different ending         man   men      foot   feet      child   children      person   people      tooth   teeth      mouse   mice  Unchanging Singular and plural are the same          sheep deer fish  sometimes

User · Answer

Both representations are useful  I had used singular for convenience for quite some time  inflection can be difficult  My experience in developing strictly singular REST APIs  the developers consuming the endpoint lack certainty in what the shape of the result may be  I now prefer to use the term that best describes the shape of the response   If all of your resources are top level  then you can get away with singular representations  Avoiding inflection is a big win   If you are doing any sort of deep linking to represent queries on relations  then developers writing against your API can be aided by having a stricter convention   My convention is that each level of depth in a URI is describing an interaction with the parent resource  and the full URI should implicitly describe what is being retrieved   Suppose we have the following model   interface User        lt string gt id       lt Friend   gt friends       lt Manager gt user     interface Friend        lt string gt id       lt User gt user          lt  lt friendship specific props gt  gt      If I needed to provide a resource that allows a client to get the manager of a particular friend of a particular user  it might look something like   GET  users  id  friends  friendId  manager  The following are some more examples    GET  users - list the user resources in the global users collection POST  users - create a new user in the global users collection GET  users  id  - retrieve a specific user from the global users collection GET  users  id  manager - get the manager of a specific user GET  users  id  friends - get the list of friends of a user GET  users  id  friends  friendId  - get a specific friend of a user LINK  users  id  friends - add a friend association to this user UNLINK  users  id  friends - remove a friend association from this user   Notice how each level maps to a parent that can be acted upon  Using different parents for the same object is counterintuitive  Retrieving a resource at GET  resource 123 leaves no indication that creating a new resource should be done at POST  resources

User · Answer

Whereas the most prevalent practice are RESTful apis where plurals are used e g   api resources 123   there is one special case where I find use of a singular name more appropriate expressive than plural names  It is the case of one-to-one relationships  Specifically if the target item is a value object in Domain-driven-design paradigm    Let us assume every resource has a one-to-one accessLog which could be modeled as a value object i e not an entity therefore no ID  It could be expressed as  api resources 123 accessLog  The usual verbs  POST  PUT  DELETE  GET  would appropriately express the intent and also the fact that the relationship is indeed one-to-one

User · Answer

My two cents  methods who spend their time changing from plural to singular or viceversa are a waste of CPU cycles  I may be old-school  but in my time like things were called the same  How do I look up methods concerning people  No regular expresion will cover both person and people without undesirable side effects   English plurals can be very arbitrary and they encumber the code needlessly  Stick to one naming convention  Computer languages were supposed to be about mathematical clarity  not about mimicking natural language

User · Answer

I prefer using singular form for both simplicity and consistency   For example  considering the following url    customer 1  I will treat customer as customer collection  but for simplicity  the collection part is removed   Another example    equipment 1  In this case  equipments is not the correct plural form  So treating it as a equipment collection and removing collection for simplicity makes it consistent with the customer case

User · Answer

To me plurals manipulate the collection  whereas singulars manipulate the item inside that collection   Collection allows the methods GET   POST   DELETE  Item allows the methods GET   PUT   DELETE  For example  POST on  students will add a new student in the school    DELETE on  students will remove all the students in the school    DELETE on  student 123 will remove student 123 from the school   It might feel like unimportant but some engineers sometimes forget the id   If the route was always plural and performed a DELETE  you might accidentally wipe your data  Whereas missing the id on the singular will return a 404 route not found   To further expand the example if the API was supposed to expose multiple schools  then something like  DELETE on  school abc students will remove all the students in the school abc    Choosing the right word sometimes is a challenge on its own  but I like to maintain plurality for the collection  E g  cart items or cart items feels right  In contrast deleting cart  deletes the cart object it self and not the items within the cart

User · Answer

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

User · Answer

From the API consumer s perspective  the endpoints should be predictable so  Ideally      GET  resources should return a list of resources   GET  resource should return a 400 level status code  GET  resources id  resourceId  should return a collection with one resource  GET  resource id  resourceId  should return a resource object  POST  resources should batch create resources  POST  resource should create a resource  PUT  resource should update a resource object  PATCH  resource should update a resource by posting only the changed attributes  PATCH  resources should batch update resources posting only the changed attributes  DELETE  resources should delete all resources  just kidding  400 status code DELETE  resource id  resourceId    This approach is the most flexible and feature rich  but also the most time consuming to develop  So  if you re in a hurry  which is always the case with software development  just name your endpoint resource or the plural form resources  I prefer the singular form because it gives you the option to introspect and evaluate programmatically since not all plural forms end in  s    Having said all that  for whatever reason the most commonly used practice developer s have chosen is to use the plural form  This is ultimately the route I have chosen and if you look at popular apis like github and twitter  this is what they do    Some criteria for deciding could be    What are my time constraints   What operations will I allow my consumers to do  What does the request and result payload look like  Do I want to be able to use reflection and parse the URI in my code    So it s up to you  Just whatever you do be consistent

User · Answer

How about    resource   not  resource    resource  means it s a folder contains something called  resource   it s a  resouce  folder   And also I think the naming convention of database tables is the same  for example  a table called  user  is a  user table   it contains something called  user

User · Answer

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

User · Answer

Use Singular and take advantage of the English convention seen in e g   Business Directory    Lots of things read this way   Book Case    Dog Pack    Art Gallery    Film Festival    Car Lot   etc   This conveniently matches the url path left to right  Item type on the left  Set type on the right   Does GET  users really ever fetch a set of users  Not usually  It fetches a set of stubs containing a key and perhaps a username  So it s not really  users anyway  It s an index of users  or a  user index  if you will  Why not call it that  It s a  user index  Since we ve named the set type  we can have multiple types showing different projections of a user without resorting to query parameters e g  user phone-list or  user mailing-list   And what about User 300  It s still  user 300   GET  user index GET  user  id   POST  user PUT  user  id   DELETE  user  id    In closing  HTTP can only ever have a single response to a single request  A path is always referring to a singular something

User · Answer

I prefer to use both plural   resources  and singular   resource  id   because I think that it more clearly separates the logic between working on the collection of resources and working on a single resource   As an important side-effect of this  it can also help to prevent somebody using the API wrongly  For example  consider the case where a user wrongly tries to get a resource by specifying the Id as a parameter like this    GET  resources Id 123   In this case  where we use the plural version  the server will most likely ignore the Id parameter and return the list of all resources  If the user is not careful  he will think that the call was successful and use the first resource in the list    On the other hand  when using the singular form    GET  resource Id 123   the server will most likely return an error because the Id is not specified in the right way  and the user will have to realize that something is wrong

User · Answer

Why not follow the prevalent trend of database table names  where a singular form is generally accepted  Been there  done that -- let s reuse   Table Naming Dilemma  Singular vs  Plural Names

User · Answer

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

User · Answer

Using plural for all methods is more practical at least in one aspect   if you re developing and testing a resource API using Postman  or similar tool   you don t need to edit the URI when switching from GET to PUT to POST etc

User · Answer

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           lt --- gt  orders  POST  orders           lt --- gt  orders push data  GET   orders 1         lt --- gt  orders 1  PUT   orders 1         lt --- gt  orders 1    data GET   orders 1 lines   lt --- gt  orders 1  lines POST  orders 1 lines   lt --- gt  orders 1  lines push data

User · Answer

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

User · Answer

An id in a route should be viewed the same as an index to a list  and naming should proceed accordingly   numbers    1  2  3   numbers            GET  numbers numbers 1          GET  numbers 1 numbers push 4     POST  numbers numbers 1    23    UPDATE  numbers 1   But some resources don t use ids in their routes because there s either only one  or a user never has access to more than one  so those aren t lists   GET  dashboard DELETE  session POST  login GET  users   id  profile UPDATE  users   id  profile

User · Answer

I don t like to see the  id  part of the URLs overlap with sub-resources  as an id could theoretically be anything and there would be ambiguity   It is mixing different concepts  identifiers and sub-resource names      Similar issues are often seen in enum constants or folder structures  where different concepts are mixed  for example  when you have folders Tigers  Lions and Cheetahs  and then also a folder called Animals at the same level -- this makes no sense as one is a subset of the other    In general I think the last named part of an endpoint should be singular if it deals with a single entity at a time  and plural if it deals with a list of entities   So endpoints that deal with a single user   GET   user             - gt  Not allowed  400 GET   user  id         - gt  Returns user with given id POST  user             - gt  Creates a new user PUT   user  id         - gt  Updates user with given id DELETE  user  id       - gt  Deletes user with given id   Then there is separate resource for doing queries on users  which generally return a list   GET  users             - gt  Lists all users  optionally filtered by way of parameters GET  users new since x - gt  Gets all users that are new since a specific time GET  users top max x   - gt  Gets top X active users   And here some examples of a sub-resource that deals with a specific user   GET  user  id  friends - gt  Returns a list of friends of given user   Make a friend  many to many link    PUT  user  id  friend  id      - gt  Befriends two users DELETE  user  id  friend  id   - gt  Unfriends two users GET  user  id  friend  id      - gt  Gets status of friendship between two users   There is never any ambiguity  and the plural or singular naming of the resource is a hint to the user what they can expect  list or object    There are no restrictions on ids  theoretically making it possible to have a user with the id new without overlapping with a  potential future  sub-resource name

User · Answer

With naming conventions  it s usually safe to say  just pick one and stick to it   which makes sense   However  after having to explain REST to lots of people  representing endpoints as paths on a file system is the most expressive way of doing it  It is stateless  files either exist or don t exist   hierarchical  simple  and familiar - you already knows how to access static files  whether locally or via http   And within that context  linguistic rules can only get you as far as the following      A directory can contain multiple files and or sub-directories  and therefore its name should be in plural form    And I like that  Although  on the other hand - it s your directory  you can name it  a-resource-or-multiple-resources  if that s what you want  That s not really the important thing   What s important is that if you put a file named  123  under a directory named  resourceS   resulting in  resourceS 123   you cannot then expect it to be accessible via  resource 123   Don t try to make it smarter than it has to be - changing from plural to singluar depending on the count of resources you re currently accessing may be aesthetically pleasing to some  but it s not effective and it doesn t make sense in a hierarchical system   Note  Technically  you can make  symbolic links   so that  resources 123 can also be accessed via  resource 123  but the former still has to exist

User · Answer

I know most people are between deciding whether to use plural or singular  The issue that has not been addressed here is that the client will need to know which one you are using  and they are always likely to make a mistake  This is where my suggestion comes from    How about both  And by that  I mean use singular for your whole API and then create routes to forward requests made in the plural form to the singular form  For example   GET   resources           GET   resource GET   resources 1         GET   resource 1 POST  resources 1         POST  resource 1       You get the picture  No one is wrong  minimal effort  and the client will always get it right

[rest] REST URI convention - Singular or plural name of resource while creating it

Examples related to rest

Examples related to resources

Examples related to naming-conventions

Examples related to uri