...

Conventions and Practices

Conventions Some conventions and practices followed in these APIs are discussed here.

REST, as an abstract architectural style, and the community of practice that has grown up around it, offers wide latitude for implementations to meet specific applications. While there are a number of suggested guides around building RESTful services, they generally offer suggestions, rather than standards or specifications.

In the case of the conventions and practices described here, there are often distinct advantages and disadvantages associated with most or all of their possible choices. Sometimes selections were made on the basis of expediency: the need to standardize on a "good enough" convention or practice, at an early stage.

Naming Conventions

• The names of path elements and query parameters are:
  • Written in the English language. Any cases where variant spellings or forms exist in different English dialects (e.g. USA and British English) will be resolved by consensus among the project team.
  • Internationalization capability for path elements and query parameters in the REST-based API to CollectionSpace services will be left open as a potential future enhancement, following release 1.0, and care will be taken to not preclude Internationalization.
  • Always written in all lowercase letters.
• The names of path elements are:
  • Always nouns.
  • Pluralized using the simplest possible pluralization rules (e.g. the plural of "person" is "persons"), where the plural form varies as little as possible in spelling and number of characters from the singular. With English language path elements, whenever possible, the plural form will append "s" or "es" to the singular form. More complex pluralization rules (e.g. in which the plural of "person" is "people," akin to Ruby on Rails' pluralization) are not used.
• When the name of a path element or query parameter would, in the English language, include a combination of multiple, space-separated word tokens, these word tokens are combined (run together) without any URL encoded characters, separators, or the use of mixed case. Examples:
  • A path element that serves as a top-level REST-based container or "bucket" for "collection objects" is written as /collectionobjects (and not /collection%20objects, /collection_objects, /collection-objects, /collection.objects, or /collectionObjects. (The latter would also violate the "written in all lowercase letters" convention above.)
  • A query parameter named "page size" is similarly written as ?pagesize={value} or &pagesize={value}, depending on its position within a set of query parameter(s).

...