Resource naming conventions in REST API design
To properly design a REST API we should look into RESTful principles, these were first introduced by Roy Fielding in Chapter 5 of his dissertation on network based software architectures. These divide the REST service into separated resources, manipulated using the different HTTP methods and that performs responses by the usage of the different http status codes.
So the basic design guidelines comprises the following:
Resources
So let's go into the details of Resource design
Names and Verbs
To describe your resources, use concrete names and not action verbs. Although this is against the typical naming conventions for decades, computer scientists used action verbs in order to expose services in an RPC way.
By contrast, the RESTful approach used in REST APIs is to use names for the resource (in plural if is a collection).
/users/1234
/users
/addresses/1234
Used together with the corresponding http methods that allows to get, create and delete.
URI case
When it comes to naming resources in a program, there are 3 main types of case conventions: CamelCase, snake_case, and spinal-case. Described both as follows:
camelCase is named after the "humps" of its capital letters, similar to the humps of a Bactrian camel
CamelCase is a naming convention in which a name is formed of multiple words that are joined together as a single word with the first letter of each of the multiple words capitalized so that each word that makes up the name can easily be read. The name derives from the hump or humps that seem to appear in any CamelCase name. In UpperCamelCase, the first letter of the new word is upper case, allowing it to be easily distinguished from a lowerCamelCase name, in which the first letter of the first name is lower case.
From wikipedia
Snake case (or snake_case) is the practice of writing compound words or phrases in which the elements are separated with one underscore character (_) and no spaces, with each element's initial letter usually lowercased within the compound and the first letter either upper- or lowercase—as in "foo_bar" and "Hello_world".
From wikipedia
Spinal-case
spinal-case is a variant of snake case which uses hyphens “-” to separate words. The pros and cons are quite similar to those of snake case, with the exception that some languages do not allow hyphens in symbol names (for variable, class, or function naming). You may find it referred to as lisp-case because it is the usual way to name variables and functions in Lisp dialects. It is also the traditional way of naming folders and files in UNIX and Linux systems. Examples: spinal-case, current-user, etc.
As stated in RFC3986 , URLs are “case sensitive” so this affects to the resource naming conventions taken.
Will discuss in other chapters the usage of http methods in REST API Design and the usage of http status codes.