Nobody likes a messy filing cabinet. It’s hard to find the documents you need when they’re not properly organized or labeled. Not having a clear system for sorting them often results in you getting an unnecessary headache. Believe it or not, the same principle applies when you use the naming conventions for RESTful APIs.
Proper usage of naming conventions is one of the most crucial aspects of REST API design. The REST method uses HTTP as its application protocol and Uniform Resource Identifiers (URIs) to address resources. When you’re naming the said URIs, the goal is to follow a uniform system without any ambiguities.
Just like labels on the folders of a filing cabinet, properly named URIs will guide your users to the resource they want to access. Aside from being correct, URIs should be written following a logical pattern. They must also be intuitive and easy for the user to understand. In addition, the naming scheme should benefit the REST API designers as well as intended clients. Following it should give the team less grief when keeping tabs on both current and future REST API resources.
Here are six things to consider when naming RESTful API resources. For best results, apply these in a reliable API Design, Planning & Modeling Tool that is sure to help you manage the task.
Nouns vs. Verbs
In the world of REST APIs, the term “resource” references a thing, such as an object or a set of objects. The definition doesn’t reference an action. This is why most URIs represent resources with nouns instead of verbs. Consider the difference between writing “/find-books” and writing “/books.” The latter is a cleaner, simpler, and more consistent way to reference a catalogue of books.
Archetypes
For better organization, you should also devise a naming scheme according to resource archetypes. Some distinctions that can be made are:
- whether the URI will lead to a single resource (“/the-great-gatsby”)
- whether the URI will lead to a collection of resources (“/classics”)
- whether the URI will lead to a resource repository, which never generates new URIs on its own (“/shopping-cart”)
- whether the URI is a controller for procedures (“/checkout”)
Plural vs. Singular
It’s also important to distinguish between single resources, such as files or documents, versus collection resources, such as a compilation of these. That distinction should be clear in the URI. A collection of jackets should be listed as “/jackets,” and a single item in that collection should be listed as “paisley-hoodie.”
Use of Characters and Letter Cases
Characters and letter cases are of key importance in URI naming. That’s why you should be careful about using each in the way that it’s conventionally understood. Common situations that involve the use of different characters and letter cases are detailed below.
Forward Slash
The forward slash (/) is a special character that’s placed in the URI’s path portion. It communicates that there’s a hierarchical relationship between the listed resources, for example “sneakers/slip-ons” or “books/classics/the-great-gatsby.” There’s no need to add a forward slash at the end of the URI, after the last resource item in the hierarchy.
Hyphens
Using hyphens is the cleanest-looking method to break up resources that are more than one word long. Doing so makes the phrase look less clumped up and more readable. Go for hyphens (“/the-great-gatsby”) as opposed to underscores (“/the_great_gatsby”).
Lower Case
With the exception of host components and schemes (“HTTP” and “BOOKS.ORG”), URIs are case-sensitive. Between upper case and lower case, the latter is often preferable in naming resources.
File Extensions
File extensions proffer no value to the URI. It’s fine to leave them out and keep the URI short. The API will also seem more credible if the emphasis is given on the media type (“/audio”) and not the whole file (“/bohemian-rhapsody.mp3”).
Query Parameters
There’s no need to create an entirely different API just to sort out or filter resources. Including query parameters in the URI will do this for you. Adding query parameters is an excellent scheme to compile resources based on what your client user needs. For example, you can write “/books?=<50” to help users search for books that are less than $50.
Conclusion: URIs as Labels for RESTful APIs
As your REST API grows, you should anticipate the need to organize more and more resources. But if you observe proper naming conventions for your URIs, this multitude of resources shouldn’t be a problem. Be careful and concise when you name these parts of your REST API.
