RESTful API Resource Naming Guide (URI Naming)

When it comes to API Design, having an API resource naming convention, which is followed consistently, is very important. Coupled with the correct use of HTTP verbs, this helps to standardize API access and reduce potential security concerns. Here's a quick guide on naming REST API resources and endpoints, which will help you design APIs which are intuitive, easy to use and will make frontend developers fall in love with you 😉.

URIs as resources (nouns)

One of the most common mistakes that API developers, including myself, make is misusing nouns and verbs in REST URIs. Here is a quick note to help you understand REST URI naming:

REST APIs are used to get and manipulate resources (nouns), not actions (verbs). Therefore, REST URIs should not indicate any kind of action or CRUD (Create, Read, Update, Delete) functionality.

Examples:

// Get all user resources
GET "https://example.com/api/v1/users" // Correct
GET "https://example.com/api/v1/listUsers" // Wrong

// Update a single photo resource
PUT "https://example.com/api/v1/photos/{id}" // Correct
PUT "https://example.com/api/v1/updatePhoto/{id}" // Wrong

Pluralized Resources

Unless you have a singleton or function resource, you should pluralize all resource names.

Examples

"/users/{id}"
"/schema" // Singleton resource
"/auth/login" // Function resource

Resource hierarchy

A resource may have sub-collection resources. Conventionally, the hierarchy between individual resources and collections is displayed using Forward slashes.

Example:
Get all order resources which fall under a single customer resource.

GET "/customers/123/orders"

Letters and dashes

Resource names must exclusively use lowercase letters. In the case of resource names with multiple words, use dashes instead of underscores or the camel case convention.

Example

"/users/123/pending-orders" // Correct
"/users/123/pendingOrders" // Wrong
"/users/123/pending_orders" // Wrong

Additional Tips

• No abridging. /users/{id}/phone-number instead of /users/{id}/tel-no
• No trailing forward slash. /users/{id}/pending-orders instead of /users/{id}/pending-orders/
• Consistency is key
• Use query parameters to filter, sort or limit a URI collection. /users?country=ZM&sort=createdAt&limit=100

Please comment to share any other best practices when it comes to RESTFul APIs.