...
REST-based APIs for Task Services
REST-based APIs for Entity Services
...
The classic example of something very hard to implement without some server side state is an e-commerce shopping cart. There are a handful of examples on the web of a "purely RESTful shopping cart," but they tend to be a bit odd ...
But one way to RESTify this model, without changing it completely, is to deconstruct the idea of the "session" a bit. Instead of having one generalized server-side bag of state (the JSP/Servlet style HttpSession), which can only be accessed using server-side code, the client can use RESTful operations to create a needed resource on the server (e.g. a ShoppingCartResource); then these resources may be exposed back to the creator using RESTful patterns.
This hypothetical ShoppingCartResource would have a URI and ... representations that can be PUT, GET, etc. ... Now you have your shopping cart abstracted in a way that you can work with it on the server side using internal requests ... OR work with it on the client side using an Applet, Flex/Flash RIA, GWT, or AJAX application.
Conventions and Practices
Conventions and practices followed in these APIs.
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.
- 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).
References
...