...

Response: Entity Body (on Error)
Returns an XML document containing a description of the error. See Common System Specific Elements for details.

Questions or Issues

• We need to decide when a POST of a new resource to a container or bucket results in a 409 Conflict error. One example may be when the value of an information unit in the POSTed resource conflicts with a value of that same information unit in an existing resource. This might occur, for instance, in the case of a RDBMS column (field) on which there is a PRIMARY KEY or UNIQUE constraint.

Read

Purpose
Reads (aka retrieves or returns) a representation of a specific instance of this resource.

...

• 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, for example, as /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).

Where possible, naming conventions should be consistent - after reflecting software-specific requirements or idioms - across all of the artifacts that pertain to a path element, including source code files, schemas, and the like.

References

Leonard Rosenthal and Sam Ruby, RESTful Web Services

RESTful Service - Ajax Patterns

Joe Gregorio, How to Create a REST Protocol