...
Some conventions and practices followed in the proposed APIs above are discussed here.
| Info |
|---|
REST is an abstract architectural style, and does not come with implementation standards or specifications, much less detailed prescriptive guidance for building REST-based APIs: whether for the services layer of a collections management system for the museum and heritage institutions community, or for any other arbitrary purpose. While there are at least several normative guides to building REST-based APIs, including those cited in References, below, they often vary in substantive ways among themselves. As a result, the Services Team has needed to make a number of choices around the design of its REST-based APIs for CollectionSpace, in the absence of a definitive specification. The conventions and practices described here document some of these choices. |
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).
...