Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
So me and my boss aren't agreeing here and can't find any information on it. Scenario: I want to get all the users for a certain organisation. What should the URL be?
mydomain.com/users/by/organisation/{orgId}
OR
mydomain.com/organisation/{orgId}/users
Our arguments:
Case 1: The call is expected to return "users" and therefore the "resource" (first part of the call) should relate to it.
Case 2: The organisation "owns"/"is the parent of" the user and therefore the organisation should be first.
What are your thoughts?
UPDATE:
I am not to worried about what comes after the mydomain.com/{resource}. The question relates mostly to whether the HTTP action (GET, POST, PUT, DELETE) should relate to the first resource mydomain.com/users or whether it should reflect the relationship mydomain.com/organisations/users/.
You are probably aware that REST has no strict rules, you are more or less free to implement it however you like, but here are my 2 cents
mydomain.com/users/by/organisation/{orgId}
However this sounds like a good url because it sort of tells you what it does by reading it, this is not a great idea. Normally, each url segment specifies a resource that exists or can exist.
In this case, users represents one or more resources and so does organisation, but by does not, it's probably nothing more than a word to help clarify what the API does.
The call is expected to return "users" and therefore the "resource" (first part of the call) should relate to it.
A resource is not necessarily specified in the first part of the url. It can be the 2nd, 3rd or 10th if you want
mydomain.com/organisation/{orgId}/users
This looks much better but I think there is 1 point of improvement. You should rename organisation to organisations, to match users
This
mydomain.com/organisations/{orgId}
then gets the organisation with id orgId, and
mydomain.com/organisations/{orgId}/users
gets all the users that belong to that organisation.
To further narrow it down you could do
mydomain.com/organisations/{orgId}/users/{userId}
to get one specific user belonging to one specific organisation
UPDATE: I am not to worried about what comes after the
mydomain.com/{resource}. The question relates mostly to whether the
HTTP action (GET, POST, PUT, DELETE) should relate to the first
resource mydomain.com/users or whether it should reflect the
relationship mydomain.com/organisations/users/.
To answer your update:
I already mentioned it above; A resource is not necessarily specified in the first part of the url.. If the quality of the url improves by shifting the wanted resource to the back of the url, go ahead and do so
There is a conceptual difference between what you are trying to show here. The first is a filtering of all the user resources in the system based on some criteria. The second is showing the user resources that belong to an organisation.
The second url is ok for showing users that belong to an organisation I think.
The first url is effectively filtering the users that you want to see from all users.
Using the url might be ok for the filtering, though using url querystring is also be ok. so
mydomain.com/users?organisationId={orgId}
might be preferable. The urls can still contain querystrings and be restful.
Does it really make any sense to DELETE mydomain.com/users/organisation/{orgid}? Would you expect that to delete the organisation? if not then this isn't really pointing at a resource and so you are doing a search, and should probably use querystrings.
There are other options for doing the search like making the search criteria a first class object, or using one of the other filtering techniques in this question or this question
Let me start with this: technically, it shouldn't really matter. REST states that URL's must be discoverable through links, like links in normal (HTML) web pages.
However, a consistent, self-explanatory URL-structure won't harm at all. I'd suggest a hierarchical structure in URLs:
/organisations returns a list of all organisations
/organisations/123 returns a specific organisation (#123)
/organisations/123/users returns a list of users that are associated to that organisation
etc.
An alternative would be using a query string for filtering:
/users returns a list of all users
/users?organisation=123 returns a list of users that are associated to that organisation
From this hierarchical perspective, /users/by/organisation/123 wouldn't make much sense. What would be the result of calling /users/by/organisation? Or /users/by?
mydomain.com/users/by/organisation/{orgId}
What does "by" mean? That has no relationship to anything. Try to keep random words out of the URL.
Case 1: The call is expected to return "users" and therefore the "resource" (first part of the call) should relate to it.
That is not a rule that RESTful APIs enforce or expect. It is really not that common in the industry either, and I have worked with a LOOOT of APIs. Consider it to be a folder.
/users - a list of users
/users/1 - user with an ID of 1
/users/1/organizations - the orgs that user belongs to
/organizations - a list of orgs
/organizations/1 - Organization number 1
/organizations/1/users - The users for that organization
You are look at it like a programmer, like it is SOAP or a PHP function, trying to make getUsersByOrganization($orgId) and that is not how REST works. :)
IF you have to stick to case 1 (first URI segment = return type) then do this:
/users?orgId=1
That is perfectly RESTful and it is essentially just a filter. You could even do both, but I wouldn't. It is a relationship which has no place there. I try and keep filters to things like: ?active=true
The second is better. Walking down the URI should narrow the request, either as filters or showing parent-child objects. Users belong to an organization, so it should be organization/users. But I'd get rid of the "organization" level of the URI too if possible.
mydomain.com/{orgId}/users
By REST the URI structure does matter only from human perspective. It does not matter from the perspective of the REST client, because it is following link annotated with semantics.
To answer your question, it matter what do you want to describe, relationships or users. If you want to add and remove relationships, then you have to define a relationship collection. If you want to add and remove users, then you have to define an user collection. This matters only by manipulation. By GET you can define any kind of query which returns a bunch of users...
This question is about optimal REST API design and a problem I'm facing to choose between nested resources and root level collections.
To demonstrate the concept, suppose I have collections City, Business, and Employees. A typical API may be constructed as follows. Imagine that ABC, X7N and WWW are keys, e.g. guids:
GET Api/City/ABC/Businesses (returns all Businesses in City ABC)
GET Api/City/ABC/Businesses/X7N (returns business X7N)
GET Api/City/ABC/Businesses/X7N/Employees (returns all employees at business X7N)
PUT Api/City/ABC/Businesses/X7N/Employees/WWW (updates employee WWW)
This appears clean because it follows the original domain structure - business are in a city, and employees are at a business. Individual items are accessible via key under the collection (e.g. ../Businesses returns all businesses, while ../Businesses/X7N returns the individual business).
Here is what the API consumer needs to be able to do:
Get businesses in a city (GET Api/City/ABC/Businesses)
Get all employees at a business (GET Api/City/ABC/Businesses/X7N/Employees)
Update individual employee information (PUT Api/City/ABC/Businesses/X7N/Employees/WWW)
That second and third call, while appearing to be in the right place, use a lot of parameters that are actually unnecessary.
To get employees at a business, the only parameter needed is the key of the business (X7N).
To update an individual employee, the only parameter needed it the key of the employee (WWW)
Nothing in the backend code requires non-key information to look up the business or update the employee. So, instead, the following endpoints appear better:
GET Api/City/ABC/Businesses (returns all Businesses in City ABC)
GET Api/Businesses/X7N (returns business X7N)
GET Api/Businesses/X7N/Employees (returns all employees at business X7N)
PUT Api/Employees/WWW (updates employee WWW)
As you can see, I've created a new root for businesses and employees, even though from a domain perspective they are a sub/sub-sub-collection.
Neither solution appears very clean to me.
The first example asks for unnecessary information, but is structured in a way that appears "natural" to the consumer (individual items from a collection are retrieved via lower leafs)
The second example only asks for necessary information, but isn't structured in a "natural" way - subcollections are accessible via roots
The individual employee root would not work when adding a new employee, as we need to know which business to add the employee to, which means that call would at least have to reside under the Business root, such as POST Api/Businesses/X7N7/Employees, which makes everything even more confusing.
Is there a cleaner, third way that I'm not thinking of?
I don't see how REST adds a constraint that two resources could not have the same value. The resourceType/ID is just an example of the easiest use case rather than the best way to go from a RESTful point of view.
If you read paragraph 5.2.1.1 of Roy Fielding's dissertation carefully, you will notice that Fielding makes the disctinction between a value and a resource. Now a resource should have a unique URI, that's true. But nothing prevents two resources from having the same value:
For example, the "authors' preferred version" of an academic paper is a mapping whose value changes over time, whereas a mapping to "the paper published in the proceedings of conference X" is static. These are two distinct resources, even if they both map to the same value at some point in time. The distinction is necessary so that both resources can be identified and referenced independently. A similar example from software engineering is the separate identification of a version-controlled source code file when referring to the "latest revision", "revision number 1.2.7", or "revision included with the Orange release."
So nothing prevents you from, as you say, changing the root. In your example, a Business is a value not a resource. It is perfectly RESTful to create a resource which is a list of "every business located in a city" (just like Roy's example, "revisions included with the Orange release"), while having a "business which ID is x" resource as well (like "revision number x").
For Employees, I would keep API/Businesses/X7N/Employees as the relation between a business and its employees is a composition relationship, and thus as you say, Employees can and should only be accessed through the Businesses class root. But this is not a REST requirement, and the other alternative is perfectly RESTful as well.
Note that this goes in pair with the application of the HATEAOS principle. In your API, the list of Businesses located in a city could (and perhaps should from a theoretical point of view) be just a list of links to the API/Businesses. But this would mean that the clients would have to do one round-trip to the server for each of the items in the list. This is not efficient and, to stay pragmatic, what I do is embed the representation of the business in the list along with the self link to the URI that would be in this example API/Businesses.
You should not confuse REST with the application of a specific URI naming convention.
HOW the resources are named is entirely secondary. You are trying to use HTTP resource naming conventions - this has nothing to do with REST. Roy Fielding himself states so repeatedly in the documents quoted above by others. REST is not a protocol, it is an architectural style.
In fact, Roy Fielding states in his 2008 blog comment (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven 6/20/2012):
"A REST API must not define fixed resource names or hierarchies (an obvious coupling of
client and server). Servers must have the freedom to control their own namespace. Instead,
allow servers to instruct clients on how to construct appropriate URIs, such as is done in
HTML forms and URI templates, by defining those instructions within media types and link relations."
So in essence:
The problem you describe is not actually a problem of REST - conceptually, it is a problem of HIERARCHY STRUCTURES versus RELATIONAL STRUCTURES.
While a business is "in" a city and so can be considered to be part of the city "hierarchy" - what about international companies which have offices in 75 cities. Then the city suddenly becomes the junior element in a hierarchy with the business name at the senior level of the structure.
The point is, you can view data from various angles, and depending on the viewpoint you take, it may be simplest to see it as a hierarchy. But the same data can be seen as a hierarchy with different levels. When you are using HTTP type resource names, then you have entered a hierarchy structure defined by HTTP. This is a constraint, yes, but it's not a REST constraint, it's a HTTP constraint.
From that angle, you can chose the solution which fits better to your scenario. If your customer cannot supply the city name when he supplies the company name (he may not know), then it would be better to have the key with only city name. As I said, it's up to you, and REST won't stand in your way ...
More to the point:
The only real REST constraints you have, if you have already decided to use HTTP with GET
PUT and so on, are:
Thou shalt not presumeth any prior ("out of band") knowledge between client and servers. *
Look at your proposal #1 above in that light. You assume that customers know the keys for the cities which are contained in your system? Wrong - that's not restful. So the server has to give the list of cities as a list of choices in some way. So are you going to list every city in the world here?
I guess not, but then you'll have to do some work on how you are planning to do this, which brings us to:
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state ...
I think, reading the mentioned Roy Fielding blog will help you out considerably.
In a RESTful-API URL design should be quite unimportant - or at least a side issue since the discoverability is encoded in the hypertext and not in the URL path. Have a look at the resources linked in the REST tag wiki here on StackOverflow.
But if you want to design human readable URLs for your UC, I would suggest the following:
Use the resource type you are creating/updating/querying as the first part of the URL (after your API prefix). So when somebody sees the URL he immediately knows to which resources this URL points. GET /Api/Employees... is the only only way to receive Employee resources from the API.
Use Unique IDs for each resource independent of the relations they are in. So GET /Api/<CollectionType>/UniqueKey should return a valid resource representation. Nobody should have to worry where the Employee is located. (But the returned Employee should have the links to the Business (and for convenience sake City) he belongs to.) GET /Api/Employees/Z6W returns the Employee with this ID no matter where is is located.
If you want to get a specific resource: Put your query parameter at the end (instead in the hierarchical order described in the question). You can use the URL query string (GET /Api/Employees?City=X7N) or a matrix parameter expression (GET /Api/Employees;City=X7N;Business=A4X,A5Y). This will allow you to easily express a collection of all Employees in a specific City - independent of the Business they are in.
Side node:
In my experience an initial hierarchical domain data model seldom survives additional requirements that come up during a project. In your case: Consider a business located in two Cities. You could create a workaround by modelling it as two separate businesses but what about the employee who works half his time in one place and the other half at the other location? Or even worse: It's only clear for which business he works but it's undefined, in which city?
The third way that I see is to make Businesses and Employees root resources and use query parameters to filter collections:
GET Api/Businesses?city=ABC (returns all Businesses in City ABC)
GET Api/Businesses/X7N (returns business X7N)
GET Api/Employees?businesses=X7N (returns all employees at business X7N)
PUT Api/Employees/WWW (updates employee WWW)
Your both solutions use concept of REST sub-resources which requires that subresource is included in parent resource so:
GET Api/City/ABC/Businesses
in response should also return data provided by:
GET Api/City/ABC/Businesses/X7N
GET Api/City/ABC/Businesses/X7N/Employees
similar for:
GET Api/Businesses/X7N
which should return data provided by:
GET Api/Businesses/X7N/Employees
It will make size of the response huge and time required to generate will increase.
To make REST API clean each resource should have only one bounded URI which fallow below patterns:
GET /resources
GET /resources/{id}
POST /resources
PUT /resources/{id}
If you need to make links between resources use HATEOAS
Go with example 1. I wouldn't worry about unnecessary information from the point of view of the server. A URL should clearly identify a resource in a unique fashion from the point of view of the client. If the client would not know what /Employee/12 means without first knowing that it is actually /Businesses/X7N/Employees/12 then the first URL seems redundant.
The client should be dealing with URLs rather than the individual parameters that make up the URLs, so there is nothing wrong with long URLs. To the client they are just strings. The server should be telling the client the URL to do what it needs to do, not the individual parameters that then require the client to construct the URL.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 4 years ago.
Improve this question
When designing resource hierarchies, when should one use sub-resources?
I used to believe that when a resource could not exist without another, it should be represented as its sub-resource. I recently ran across this counter-example:
An employee is uniquely identifiable across all companies.
An employee's access control and life-cycle depend on the company.
I modeled this as: /companies/{companyName}/employee/{employeeId}
Notice, I don't need to look up the company in order to locate the employee, so should I? If I do, I'm paying a price to look up information I don't need. If I don't, this URL mistakenly returns HTTP 200:
/companies/{nonExistingName}/employee/{existingId}
How should I represent the fact that a resource to belongs to another?
How should I represent the fact that a resource cannot be identified without another?
What relationships are sub-resources meant and not meant to model?
A year later, I ended with the following compromise (for database rows that contain a unique identifier):
Assign all resources a canonical URI at the root (e.g. /companies/{id} and /employees/{id}).
If a resource cannot exist without another, it should be represented as its sub-resource; however, treat the operation as a search engine query. Meaning, instead of carrying out the operation immediately, simply return HTTP 307 ("Temporary redirect") pointing at the canonical URI. This will cause clients to repeat the operation against the canonical URI.
Your specification document should only expose root resources that match your conceptual model (not dependent on implementation details). Implementation details might change (your rows might no longer be unique identifiable) but your conceptual model will remain intact. In the above example, you'd tell clients about /companies but not /employees.
This approach has the following benefits:
It eliminates the need to do unnecessary database look-ups.
It reduces the number of sanity-checks to one per request. At most, I have to check whether an employee belongs to a company, but I no longer have to do two validation checks for /companies/{companyId}/employees/{employeeId}/computers/{computerId}.
It has a mixed impact on database scalability. On the one hand you are reducing lock contention by locking less tables, for a shorter period of time. But on the other hand, you are increasing the possibility of deadlocks because each root resource must use a different locking order. I have no idea whether this is a net gain or loss but I take comfort in the fact that database deadlocks cannot be prevented anyway and the resulting locking rules are simpler to understand and implement. When in doubt, opt for simplicity.
Our conceptual model remains intact. By ensuring that the specification document only exposes our conceptual model, we are free to drop URIs containing implementation details in the future without breaking existing clients. Remember, nothing prevents you from exposing implementation details in intermediate URIs so long as your specification declares their structure as undefined.
This is problematic because it's no longer obvious that a user belongs
to a particular company.
Sometimes this may highlight a problem with your domain model. Why does a user belong to a company? If I change companies, am I whole new person? What if I work for two companies? Am I two different people?
If the answer is yes, then why not take some company-unique identifier to access a user?
e.g. username:
company/foo/user/bar
(where bar is my username that is unique within that specific company namespace)
If the answer is no, then why am I not a user (person) by myself, and the company/users collection merely points to me: <link rel="user" uri="/user/1" /> (note: employee seems to be more appropriate)
Now outside of your specific example, I think that resource-subresource relationships are more appropriate when it comes to use rather than ownership (and that's why you're struggling with the redundancy of identifying a company for a user that implicitly identifies a company).
What I mean by this is that users is actually a sub-resource of a company resource, because the use is to define the relationship between a company and its employees - another way of saying that is: you have to define a company before you can start hiring employees. Likewise, a user (person) has to be defined (born) before you can recruit them.
Your rule to decide if a resource should be modeled as sub resource is valid. Your problem does not arise from a wrong conceptual model but you let leak your database model into your REST model.
From a conceptual view an employee if it can only exist within a company relationship is modeled as a composition. The employee could be thus only identified via the company. Now databases come into play and all employee rows get a unique identifier.
My advice is don't let the database model leak in your conceptional model because you're exposing infrastructure concerns to your API. For example what happens when you decide to switch to a document oriented database like MongoDB where you could model your employees as part of the company document and no longer has this artificial unique id? Would you want to change your API?
To answer your extra questions
How should I represent the fact that a resource to belongs to another?
Composition via sub resources, other associations via URL links.
How should I represent the fact that a resource cannot be identified without another?
Use both id values in your resource URL and make sure not to let your database leak into your API by checking if the "combination" exists.
What relationships are sub-resources meant and not meant to model?
Sub resources are well suited for compositions but more generally spoken to model that a resource cannot exist without the parent resource and always belongs to one parent resource. Your rule when a resource could not exist without another, it should be represented as its sub-resource is a good guidance for this decision.
if a subresource is uniquely identifiable without its owning entity, it is no subresource and should have its own namespace (i.e. /users/{user} rather than /companies/{*}/users/{user}).
Most importantly: never ever ever everer uses your entity's database primary key as the resource identifier. that's the most common mistake where implementation details leak to the outside world. you should always have a natural business key (like username or company-number, rather than user-id or company-id). the uniqueness of such a key can be enforced by a unique constraint, if you wish, but the primary key of an entity should never ever everer leave the persistence-layer of your application, or at least it should never be an argument to any service method. If you go by this rule, you shouldn't have any trouble distinguishing between compositions (/companies/{company}/users/{user}) and associations (/users/{user}), because if your subresource doesn't have a natural business key, that identifies it in a global context, you can be very certain it really is a depending subresource (or you must first create a business key to make it globally identifiable).
This is one way you can resolve this situation:
/companies/{companyName}/employee/{employeeId} -> returns data about an employee, should also include the person's data
/person/{peopleId} -> returns data about the person
Talking about employee makes no sense without also talking about the company, but talking about the person does make sense even without a company and even if he's hired by multiple companies. A person's existence is independent of whether he's hired by any companies, but an employment's existence does depend on the company.
The issue seems to be when there is no specific company but an employee technically belongs to some company or organization otherwise they could be called bums or politicians. Being an employee implies a company/organization relationship somewhere but not a specific one. Also employees can work for more than one company/organization. When the specific company context is required then your original works /companies/{companyName}/users/{id}
Lets say you want to know the EmployerContribution for your ira/rsp/pension you'd use:
/companies/enron/users/fred/EmployerContribution
You get the specific amount contributed by enron (or $0).
What if you want the EmployerContributions from any or all companies fred works(ed) for? You don't need a concrete company for it to make sense. /companies/any/employee/fred/EmployerContribution
Where "any" is obviously an abstraction or placeholder when the employee's company doesn't matter but being an employee does. You need to intercept the 'company" handler to prevent a db lookup (although not sure why company wouldn't be cached? how many can there be?)
You can even change the abstraction to represent something like all companies for which Fred was employed over the last 10 years.
/companies/last10years/employee/fred/EmployerContribution
Some RESTful services use different resource URIs 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. Should we use plural or singular for resource creation? What should be the criteria while deciding that?
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)
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.
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.
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?
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
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
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.
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)
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.
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.
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 PUT /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 /session
GET /users/{:id}/profile
PUT /users/{:id}/profile
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.
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.
The Most Important Thing
Any time you are using plurals in interfaces and code, ask yourself, how does your convention handle words like these:
/pants, /eye-glasses - are those the singular or the plural path?
/radii - do you know off the top of your head if the singular path for that is /radius or /radix?
/index - do you know off the top of your head if plural path for that is /indexes or /indeces or /indices?
Conventions should ideally scale without irregularity. English plurals do not do this, because
they have exceptions like one of something being called by the plural form, and
there is no trivial algorithm to get the plural of a word from the singular, get the singular from the plural, or tell if an unknown noun is singular or plural.
This has downsides. The most prominent ones off the top of my head:
The nouns whose singular and plural forms are the same will force your code to handle the case where the "plural" endpoint and the "singular" endpoint have the same path anyway.
Your users/developers have to be proficient with English enough to know the correct singulars and plurals for nouns. In an increasingly internationalized world, this can cause non-negligible frustration and overhead.
It singlehandedly turns "I know /foo/{{id}}, what's the path to get all foo?" into a natural language problem instead of a "just drop the last path part" problem.
Meanwhile, some human languages don't even have different singular and plural forms for nouns. They manage just fine. So can your API.
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!
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 -> Not allowed, 400
GET /user/{id} -> Returns user with given id
POST /user -> Creates a new user
PUT /user/{id} -> Updates user with given id
DELETE /user/{id} -> Deletes user with given id
Then there is separate resource for doing queries on users, which generally return a list:
GET /users -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x -> Gets top X active users
And here some examples of a sub-resource that deals with a specific user:
GET /user/{id}/friends -> Returns a list of friends of given user
Make a friend (many to many link):
PUT /user/{id}/friend/{id} -> Befriends two users
DELETE /user/{id}/friend/{id} -> Unfriends two users
GET /user/{id}/friend/{id} -> 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.
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.
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.
Here's Roy Fielding dissertation of "Architectural Styles and the Design of Network-based Software Architectures", and this quote might be of your interest:
A resource is a conceptual mapping
to a set of entities, not the entity that corresponds to the mapping at any particular point in
time.
Being a resource, a mapping to a set of entities, doesn't seem logical to me, to use /product/ as resource for accessing set of products, rather than /products/ itself. And if you need a particular product, then you access /products/1/.
As a further reference, this source has some words and examples on resource naming convention:
https://restfulapi.net/resource-naming/
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.
Great discussion points on this matter. Naming conventions or rather not establishing local standards has been in my experience the root cause of many long nights on-call, headaches, risky refactoring, dodgy deployments, code review debates, etc, etc, etc. Particularly when its decided that things need to change because insufficient consideration was given at the start.
An actual issue tracked discussion on this:
https://github.com/kubernetes/kubernetes/issues/18622
It is interesting to see the divide on this.
My two cents (with a light seasoning of headache experience) is that when you consider common entities like a user, post, order, document etc. you should always address them as the actual entity since that is what a data model is based on. Grammar and model entities shouldn't really be mixed up here and this will cause other points of confusion. However, is everything always black and white? Rarely so indeed. Context really matters.
When you wish to get a collection of users in a system, for example:
GET /user -> Collection of entity User
GET /user/1 -> Resource of entity User:1
It is both valid to say I want a collection of entity user and to say I want the users collection.
GET /users -> Collection of entity User
GET /users/1 -> Resource of entity User:1
From this you are saying, from the collection of users, give me user /1.
But if you break down what a collection of users is... Is it a collection of entities where each entity is a User entity.
You would not say entity is Users since a single database table is typically an individual record for a User. However, we are talking about a RESTful service here not a database ERM.
But this is only for a User with clear noun distinction and is an easy one to grasp. Things get very complex when you have multiple conflicting approaches in one system though.
Truthfully, either approach makes sense most of the time bar a few cases where English is just spaghetti. It appears to be a language that forces a number of decisions on us!
The simple fact of the matter is that no matter what you decide, be consistent and logical in your intent.
Just appears to me that mixing here and there is a bad approach! This quietly introduces some semantic ambiguity which can be totally avoided.
Seemingly singular preference:
https://www.haproxy.com/blog/using-haproxy-as-an-api-gateway-part-1/
Similar vein of discussion here:
https://softwareengineering.stackexchange.com/questions/245202/what-is-the-argument-for-singular-nouns-in-restful-api-resource-naming
The overarching constant here is that it does indeed appear to be down to some degree of team/company cultural preferences with many pros and cons for both ways as per details found in the larger company guidelines. Google isn't necessarily right, just because it is Google! This holds true for any guidelines.
Avoid burying your head in the sand too much and loosely establishing your entire system of understanding on anecdotal examples and opinions.
Is it imperative that you establish solid reasoning for everything. If it scales for you, or your team and/our your customers and makes sense for new and seasoned devs (if you are in a team environment), nice one.
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 {
<string>id;
<Friend[]>friends;
<Manager>user;
}
interface Friend {
<string>id;
<User>user;
...<<friendship specific props>>
}
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
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 ;).
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".
Just be consistent.
Use either singular:
POST /resource
PUT /resource/123
GET /resource/123
or plural:
POST /resources
PUT /resources/123
GET /resources/123
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.