REST API Tutorial

REST Resource Naming Guide

In REST, primary data representation is called Resource.  Having a strong and consistent REST resource naming strategy – will definitely prove your one of the best design decisions in long term.

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. 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.Roy Fielding’s dissertation

A resource can be a singleton or a collection. For example, “customers” is a collection resource and “customer” is a singleton resource (in a banking domain). We can identify “customers” collection resource using the URI “/customers”. We can identify a single “customer” resource using the URI “/customers/{customerId}”.

A resource may contain sub-collection resources also. For example, sub-collection resource “accounts” of a particular “customer” can be identified using the URN “/customers/{customerId}/accounts” (in a banking domain). Similarly, a singleton resource “account” inside the sub-collection resource “accounts” can be identified as follows: “/customers/{customerId}/accounts/{accountId}”.

REST APIs use Uniform Resource Identifiers (URIs) to address resources. REST API designers should create URIs that convey a REST API’s resource model to its potential client developers. When resources are named well, an API is intuitive and easy to use. If done poorly, that same API can feel difficult to use and understand.

The constraint of uniform interface is partially addressed by the combination of URIs and HTTP verbs and using them in line with the standards and conventions.

Below are a few tips to get you going when creating the resource URIs for your new API.

REST Resource Naming Best Practices

Use nouns to represent resources

RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes. Some examples of a resource are:

  • Users of the system
  • User Accounts
  • Network Devices etc.

and their resource URIs can be designed as below:

http://api.example.com/device-management/managed-devices 
http://api.example.com/device-management/managed-devices/{device-id} 
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}

For more clarity, let’s divide the resource archetypes into four categories (document, collection, store and controller) and then you should always target to put a resource into one archetype and then use it’s naming convention consistently. For uniformity’s sake, resist the temptation to design resources that are hybrids of more than one archetype.

  1. document

    A document resource is a singular concept that is akin to an object instance or database record. In REST, you can view it as a single resource inside resource collection. A document’s state representation typically includes both fields with values and links to other related resources.

    Use “singular” name to denote document resource archetype.

    http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

  2. collection

    A collection resource is a server-managed directory of resources. Clients may propose new resources to be added to a collection. However, it is up to the collection to choose to create a new resource, or not. A collection resource chooses what it wants to contain and also decides the URIs of each contained resource.

    Use “plural” name to denote collection resource archetype.

    http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

  3. store

    A store is a client-managed resource repository. A store resource lets an API client put resources in, get them back out, and decide when to delete them. A store never generates new URIs. Instead, each stored resource has a URI that was chosen by a client when it was initially put into the store.

    Use “plural” name to denote store resource archetype.

    http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists

  4. controller

    A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

    Use “verb” to denote controller archetype.

    http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

Consistency is the key

Use consistent resource naming conventions and URI formatting for minimum ambiguily and maximum readability and maintainability. You may implement below design hints to achieve consistency:

  1. Use forward slash (/) to indicate a hierarchical relationships

    The forward slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources. e.g.

    http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

  2. Do not use trailing forward slash (/) in URIs

    As the last character within a URI’s path, a forward slash (/) adds no semantic value and may cause confusion. It’s better to drop them completely.

    http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices 	/*This is much better version*/

  3. Use hyphens (-) to improve the readability of URIs

    To make your URIs easy for people to scan and interpret, use the hyphen (-) character to improve the readability of names in long path segments.

    http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation  //Less readable

  4. Do not use underscores ( _ )

    It’s possible to use an underscore in place of a hyphen to be used as separator – But depending on the application’s font, it’s possible that the underscore (_) character can either get partially obscured or completely hidden in some browsers or screens.

    To avoid this confusion, use hyphens (-) instead of underscores ( _ ).

    http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  //More readable
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location  //More error prone

  5. Use lowercase letters in URIs

    When convenient, lowercase letters should be consistently preferred in URI paths.

    RFC 3986 defines URIs as case-sensitive except for the scheme and host components. e.g.

    http://api.example.org/my-folder/my-doc  //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc  //2
http://api.example.org/My-Folder/my-doc  //3

    In above examples, 1 and 2 are same but 3 is not as it uses My-Folder in capital letters.

  6. Do not use file extenstions

    File extensions look bad and do not add any advantage. Removing them decrease the length of URIs as well. No reason to keep them.

    Apart from above reason, if you want to highlight the media type of API using file extenstion then you should rely on the media type, as communicated through the Content-Type header, to determine how to process the body’s content.

    http://api.example.com/device-management/managed-devices.xml  /*Do not use it*/
http://api.example.com/device-management/managed-devices 	/*This is correct URI*/

Never use CRUD function names in URIs

URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.

HTTP GET http://api.example.com/device-management/managed-devices  //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices  //Create new Device

HTTP GET http://api.example.com/device-management/managed-devices/{id}  //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id}  //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id}  //Delete device for given Id

Use query component to filter URI collection

Many times, you will come across requirements where you will need a collection of resources sorted, filtered or limited based on some certain resource attribute. For this, do not create new APIs – rather enable sorting, filtering and pagination capabilities in resource collection API and pass the input parameters as query parameters. e.g.

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date

Comments

  1. http://api.example.com/song-management/users/{id}/playlists

    in php does this mean this?

    $_GET[‘song-management’] = ‘users’;
    $_GET[{id}] = ‘playlists’;

    or it’s actually..

    $_GET[‘page’] = ‘song-management’;
    $_GET[‘find’] = ‘users’;
    $_GET[‘select’] = {id};
    $_GET[‘show’] = ‘playlists’;

    i’m a bit lost in how the API’s URI should behave and how in php would think.

    Reply

  2. Any thoughts on how to handle something like tiers/grades/reliability-levels in the API resource naming? The use case being that the same resource path has the option to go via two different paths. Functionally, both the paths do the same thing, such that hitting either path would have the same result (based on what API is expected to do), but the approach taken is different, which leads to some non functional differences. It is not also an optional thing in a sense that certain set of objects are meant to hit one tier vs the other.
    A simple example being a logging API

    POST /v1/logs

    whose job is to dump the log into the system. But based on what tier was chosen, the availability/indexing/replication of logs may change.

    Should this tier information be incorporated as part of the url or should it be placed somewhere else?

    Something like

    POST /v1/tier1/logs
    Reply

    • POST are not intended to do what PUT does. A POST should always create a new resource where a PUT replaces an existing one.

      You’re free to use HTTP however you want, but if you go down that road, it’s no longer a REST API. I know if I come across a partner’s API that uses POST for every operation I tend to roll my eyes and it gives me the impression that they don’t quite know what they’re doing.

      If I were you, I would reconsider your stance on other HTTP verbs and study their purpose before committing to another non-REST, HTTP based API structure simply for “convenience”.

      Reply

  4. Hi, I’m new to API.

    The example u given using the “/” where it seems to be using “path name” as “argument” or they are actually different directories?

    http://api.example.com/device-management/managed-devices/{device-id}

    meaning?
    api.example.com/index.php
    — device-management/index.php
    — — managed-devices/index.php
    — — — {device-id}/index.php

    i got a feeling im getting this wrong. (seriously wrong)

    Reply

  5. Hi,
    You say elsewhere that a resource should have a single logical URI. But the example “/customers/{customerId}/accounts/{accountId}” could also be written “/accounts/{accountId}”, given that account IDs should be unique within a bank. So the URI is not unique.

    Reply

    • Very good question. I will argue two things.

      1) Account Id and account number are two different things. Account numbers are NPI (sensitive) data so I will never put them in URI/URL. Account id is some generated number (like primary key) for account record.

      2) accountIds in both URIs can be different numbers. In /accounts/{accountId}, it will be primary key for account record, while in second case it will be primary key which holds the relationship between account and customer. (It is just one example).

      Please note I am saying these ids to be primary keys in respective tables just me make things more relatable. An id can be a derived value as well.

      Reply

  6. Excellent article, thank you for your hard work. Could you please provide a suggestion on:

    1. if we were to use a sensitive information like insuranceId as a search criteria, should the search be made GET or POST? (since everyone says that providing sensitive information in GET URL is not a good idea)

    2. How to handle GET search if we have complicated search criteria like:- searching on a user where first_name starts with a and age is greater than 17 and sort by last_name and show pages 3-7

    Reply

  7. Hi,
    Its a good article, but the terminologies store & action was not found anywhere, Is it your convention or a standard one ?

    Reply

  8. Thanks for the article! Been looking for something just like this! One part still confuses me however:

    You recommend above to use the following for collections:

    http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

    But wouldn’t the system just look at /users/admin and think that “admin” is a user ID? This is a problem I’ve run into before, and is actually what I was researching when I came across this post 🙂 As soon as you allow resources/{variable}, you can no longer put any controller verbs or anything after /resources/ because it’ll get interpreted as your variable.

    One workaround for this seems to be changing around the order you list your URLs in in your backend, putting the catch-all URL looking for a variable last. But that’s always seemed a little hack-y and I don’t like that it imposes restrictions on how I might want to organize my URLs in the backend.

    Any suggestions for this? Is that workaround in fact standard practice?

    Thanks.

    Reply

    • I had used 3 different examples to represent the document resource. It was never meant to be used collectively. I will also not recommend to use /{id} and /admin both for same API.

      Rather I will go for /roles/{roleName} e.g. /roles/{admin} which will return all users with admin access.

      Reply

    • It’s also possible to have only numeric IDs. So the server script could distinguish wether it’s an ID or a role/username/whatever. Of course that also imposes some additional limitations like prohibiting numeric and duplicate usernames. Having “/users/{username}” and “/users/{user-id}” wouldn’t seem too illogical though (but on the other hand: what’s the purpose?). For roles I’d use another way so no one gets confused. You could even use “/users/{numeric-userid}” and “/users/roles/{role-id}” on the same api if you wanted to.

      Reply

  9. Well summarized blog.

    I’m curious to find out what you think about designing the user authentication aspects of an application.

    I was thinking of following the Controller archetype as follows:

    For login:

    .../user/login

    For logout:

    .../users/{id}/logout
    Reply

    • /login and /logout are good enough for me. No need to put “id” in request path, because it will be stored in session in the server.

      Also, I will not put /user in the URL until I have a good reason for it.

      Reply

  10. Very good article, but I have a question,

    How could you do if you wanted an API that has the following functions with differents QueryString/ParameterString/Body/Headers in a Messaging App?

    Example:
    SendMessage
    RedirectMessage
    RedirectToMessageBlock
    ForwardMessage
    UpdateAttributesInMessage

    All these functions are POST, but If you have a resource name “Message”, you can only have one POST,

    http://www.yoursite.com/api/v1/messages

    Reply

  12. Use “singular” name to denote document resource archetype.

    http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

    But why plural is used ??

    Reply

  13. About Document archetype. We can do a get/put/delete/patch because we pass an “id”, it’s fine! Is there a situation where you can use a POST on a document. In which case we can we use POST on a Document archetype?

    If you see this presentation
    https://fr.slideshare.net/domenicdenicola/creating-truly-res-tful-apis

    What do you thing about =>page 4 Resource Archetype Document /users/0987/settings. Following you this example would not it be rather relative to controller Archetype ?

    What do you thing about => page 5 Archetypye collection : Could you explain the usage of PUT for a collection? It would be in the case where one wishes to replace ALL documents. My understanding A collection is not related to a specific ID. I doesn’t understand why the author mention PATCH and DELETE on an archetype collection also? Can you enlighten me on what is “true” of “false”

    Reply

  14. What are the rules for identifying a complex resource by separating a url path? For eg., one of my resource is grouped by 2 tokens. Token one can have many other tokens. The format I am using is:

    abc.com/tokens/5678/2345

    But there is no page for abc.com/tokens/5678. Should I club “5678/2345” as “5678-2345” or using any other character?

    Reply

  15. Sir,

    I liked your blog. I would suggest to add few navigation buttons (like next, previous, top, bottom) as to continue the flow of learning and avoid scrolling.

    Reply

  16. “Do not use trailing forward slash (/) in URIs”

    I could not disagree more. Resources are in a tree structure, like a file system. URIs in browsers already behave that way as well.

    Trailing forward slash designate a collection, it’s like a file system directory. Consider the following:

    current uri: http://example.com/test and `` would link to http://example.com/
    current uri: http://example.com/test/ and `` would link to http://example.com/test/

    Exactly same behavior for a Unix-like file system.

    All collections should have a trailing slash, without just relying on the name ending with “s” (though I agree with naming collections using plural).

    Reply

      • Thats a very opinionated response.

        Lewis couldn’t be more precise and logic about the functioning.

        Case 1:

        When you compose APIs in a navigating through the hierarchy you add the name of the resource without an initial slash because it will specified that your are defining the root path.

        Eg. If you define an URI for a resource an compose an HTML based on that that uri refers to the root so will be wrong

        Case 2:

        Developer define endpoint in his/her application without trailing slash and the wants to compile a full UIR with and ID to get sub-resources why you force to pass and ID with and / obviously this goes in the endpoint and you don’t want to define 2 endpoints one for listing and one for the sub-resource.

        Reply

  19. Is it RESTful to use URI with query parameters for performing a POST/PATCH to a subset of a collection? For example, if I want to set all the live hosts in the Miami datacenter to status “dead”:

    POST /hosts?datacenter=miami&status=live
    { “status”: “dead” }

    In the response, I would include all the updated hosts and new status. Some fields (e..g hostname, IP address, etc.) would not be modifiable via this method, which would lead a 4XX status code and appropriate error message.

    Reply

  20. I like to use this way of calling custom methods or what you call “controllers”.
    https://cloud.google.com/apis/design/custom_methods

    Basically when you need to perform a special action over a resource that can’t be represented you add the action after a colon at the end.

    For example I have this /groups/{id} resource I want to clone, but there is no such method or similar in HTTP, I could just use POST /groups/{id} with the fetched data of the group I want to clone but If I want to execute that in just one action, so I add /groups/{id}:clone .

    As stated in the link, there are some considerations when doing this, like using only POST method, but is more clear this way when are you executing something or not.

    Also this maps seamlessly with auth scopes. In this case my scope would be ‘groups:clone’.

    Thanks for all this huge documentation, it is really helpful.

    Reply

  21. Wich pattern i can use in a model with a composite key?

    I have an entity called leaderboard that has a key composed by frontend + packagename, how would my endpoint for get a single leaderboard?

    GET /leaderboard/{frontend}?packagename={packagename} ?
GET /leaderboard/{frontend}-{packagename} ?
GET /leaderboard/{frontend}/{packagename} ?
    Reply

    • 1) If a frontend has many packages (in sinle screen) then GET /leaderboard/{frontend}-{packagename} does not make sense to me. Same for /leaderboard/{frontend}/{packagename}. I would not like to make N API calls to load one screen.
      2) GET /leaderboard/{frontend}?packagename={packagename} looks more flexible to me because it gives you freedom to fetch 1-N packages in single call.

      I am expressing my thoughts purely on assumption of your system. I may be incorrect, so please research.

      Reply

    • Very good observation. But this suggestion does not fit here. Reason is the URL structure. Generally in REST APIs, you pass GET parameters after “?” character. e.g. https://howtodoinjava.com?page=2 [It is invalid URL as per design of blog].

      In blogs, mostly paging parameters are passed as https://howtodoinjava.com/page/2/ [Valid URL].

      So, I say its per design followed in most wordpress blogs. And it is not recommended for REST APIs though its possible.

      Reply

  23. Very good article. To the point and very clear. Examples are very useful to understand the guideline.

    Reply

  24. Hi,

    I have a requirement where within the hierarchical data one of the resource is a collection instead of single id. What is the best way of modelling it? Example below

    Requirement: Give me access control list for specific list of roles. One way of modelling it is to allow only one role id, let the consumer call the API multiple times.
    access-management/roles/{id}/acls

    However, I want to receive all roles in one request and the response to be then able to return ACLs for all roles. Something along the lines
    access-management/roles/{ids}/acls

    What is the best way to model the API to adhere to REST and URI guidelines?

    Reply

    • Though, multiple “ACL”s can belong to single role (as sub-collection), still I see it independent resource different from “Role”. So model them accordingly.

      I will suggest to create following APIs.

      HTTP GET access-management/roles
      HTTP GET access-management/roles/{id}
      HTTP GET access-management/roles/{id}/acls

      HTTP GET access-management/acls
      HTTP GET access-management/acls/{id}

      So, to reply your query, you can use “access-management/roles” having response like this:

      <roles>
	<role id="1" uri="/access-management/roles/1">
		<name>admin</name>
		<enabled>true</enabled>
		<acls>
			<acl id="11" uri="/access-management/acls/11">
				<name>ADD</name>
				<enabled>true</enabled>
			</acl>
			<acl id="12" uri="/access-management/acls/12">
				<name>DELETE</name>
				<enabled>true</enabled>
			</acl>
		</acls>
	</role>
	<role id="2" uri="/access-management/roles/2">
		<name>user</name>
		<enabled>true</enabled>
		<acls>
			<acl id="11" uri="/access-management/acls/11">
				<name>ADD</name>
				<enabled>true</enabled>
			</acl>
		</acls>
	</role>
</roles>

      Here you can iterate all rows and find related ACLs. If you want to fetch full details of any single ACL the follow its uri attribute. Feel free to add/remove fields as per design.

      Reply

  26. A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.
    Is it RESTful?

    Reply

      • checkout is a verb and play are verbs and as you point out at the start it is considered bad practice to use verbs in the URI.

        “RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb)”

        Also you haven’t mentioned which HTTP method should be called for the controller pattern but if it is GET then you are changing state via a method that should be idempotent.

        If it is POST then the controller pattern is RPC rather than REST. A RESTful API would allow the retrieval of the “checkout” resource via

        “GET http://api.example.com/cart-management/users/{id}/cart/checkout”

        which doesn’t seem to make sense as a request.

        It would be better IMO to include a status attribute in the cart resource and update that.

        Reply

        • We can put actions in controller resources which are not logically mapped to any of CRUD operations e.g.

          POST /device-management/{id}/alerts/{id}/resend

          Above operation does not fall under CRUD.

          Reply

          • Would it be fair to say that “resend,” while not a direct CRUD type is actually a “Transaction” if we relate it to the Relational Database World?

Ask Questions & Share Feedback

Your email address will not be published. Required fields are marked *

*Want to Post Code Snippets or XML content? Please use [java] ... [/java] tags otherwise code may not appear partially or even fully. e.g.
[java] 
public static void main (String[] args) {
...
} 
[/java]