Conventions

Conventions#

Naming Convention for REST API Resources and Endpoints#

Nouns versus Verbs#

Rule: Use nouns to represent resources.

Do:

/my-folder
/@registry
/@types

Don't:

/createFolder
/deleteDocument
/updateEvent

Reason:

RESTful URIs should refer to a resource that is a thing (noun) instead of referring to an action (verb). Nouns have properties, whereas verbs do not. The REST architectural principle uses HTTP verbs to interact with resources.

There is an exception to that rule. Verbs can be used for specific actions or calculations, for example:

/login
/logout
/move-to
/reset-password

Singular versus Plural#

Rule: Use plural resources.

Do:

/users
/users/21

Don't:

/user
/user/21

Reason:

If you use singular for a collection-like resource—such as /user to retrieve a list of all users—it feels wrong. Mixing singular and plural is confusing. For example, using /users for retrieving users, and /user/21 to retrieve a single user.

URL Parameters (singular vs plural)#

Rule: Use plural for URL parameters that can contain one or multiple items. Use singular for parameters that can contain only one single item.

Do:

If the parameter allows passing multiple values:

/tokens

If the parameter allows passing a single value only:

/token

Don't:

If the parameter allows passing multiple values, do not use the singular form, and do not append a type to the variable name. The following are examples of what not to do:

/token
/token_list
/token_array
/token_set

Reason:

The naming should clearly indicate if an attribute expects a single (singular) item or multiple items (plural). We decided to use the plural form, instead of appending a possible type—such as _list, _array, or _set—to the variable name.

See plone/plone.restapi#1295 for the discussion that led to this decision.

Uppercase versus Lowercase#

Rule: Use lowercase letters in URIs.

Do:

https://example.com/my-folder/my-document

Don't:

https://example.com/My-Folder/My-Document

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

Those two URIs are equivalent:

https://example.org/my-folder/my-document
HTTPS://EXAMPLE.ORG/my-folder/my-document

While this one is not equivalent to the two URIs above:

https://example.org/My-Folder/my-document

To avoid confusion we always use lowercase letters in URIs.

Naming Convention for attribute names in URIs#

Rule: Use hyphens (spinal case) to improve readability of URIs.

Do:

/users/noam/reset-password

Don't:

/users/noam/resetPassword
/users/noam/ResetPassword
/users/noam/reset_password

Reason:

Spinal case is easier to read and safer to use than camelCase. URLs are case-sensitive (RFC3986). Plone uses spinal case for URL creation. The page title "My page" becomes "my-page". Mixed naming conventions in URLs would be confusing. For example, /my-folder/@send_url_to_user, is confusing. Google recommends spinal-case in URLs for better search engine optimization.

Discussion:

plone/plone.restapi#194

Naming Convention for attribute names in response body#

Rule: Use snake_case to reflect Python best practices.

Do:

{
  translation_of: ...
}

Don't:

{
  translationOf: ...,
  TranslationOf: ...,
}

Reason:

We map over Python attributes one-to-one whether they are snake case (modern Python and Plone, and Dexterity) or lowerCamelCase (Zope 2, Archetypes).

Versioning#

Versioning APIs makes a lot of sense for public API services. This is especially true when an API provider needs to ship different versions of the API at the same time. Plone already has a way to version packages. It currently does not make sense for us to expose that information via the API. We will always just ship one version of the API at a time. We are usually in full control over the backend and the frontend.

Contents