= RESTful JSON =

== Charter ==

Given that:
* [http://en.wikipedia.org/wiki/Representational_State_Transfer REST] is a powerful architecture for scalable web services
* [http://www.json.org/ JSON] is a lightweight container for exchanging data
* [http://tools.ietf.org/html/rfc5023 AtomPub], while RESTful, requires XML documents with strict metadata requirements

The goal of the RESTful JSON project is to develop a series of conventions for:
* URLs
* HTTP methods
* HTTP headers
* JSON fields
that:
# is maximally compatible with existing (RESTful, generic) clients
# enables partial updates
# allows paging and/or partial returns of large datasets
# standardizes linking to related resources
# use of hypermedia (links + context) to manage application state
# does NOT become a full-fledged [http://hideoustriumph.wordpress.com/2008/05/05/ws-deathstar-for-the-rest-of-us/ RPC] solution

== Resources ==
* [http://bitworking.org/news/restful_json Original proposal] by Joe Gregorio
* [http://www.json.com/2008/08/19/standardizing-restful-json/ Standardizing RESTful JSON] by Kris Zyp
* [http://groups.google.com/group/restful-json Google Group]
* [http://tools.ietf.org/html/rfc5023 AtomPub] (for comparison/inspiration)

== Proposals ==
* [[rest/urls]]
* [[rest/json-collections]]
* [http://www.sitepen.com/blog/2008/06/17/json-referencing-in-dojo/ JSON Referencing]

== Issues ==
* Is the top-level entity a simple array (Persevere, Dojo) or a full-fledged object (CouchDB, ActiveRecord?)

== Implementations ==
* [http://incubator.apache.org/couchdb/docs/intro.html CouchDB]
* [http://giantrobots.thoughtbot.com/2007/4/2/jester-javascriptian-rest Jester] (same URLs as ActiveResource)
* [http://www.sitepen.com/blog/2008/06/13/restful-json-dojo-data/ Dojo REST store]
* [http://code.google.com/p/dom-resource/ DOM Resource]
* [http://sitepen.com/labs/persevere.php Persevere]
* [http://github.com/sproutit/sproutcore/wikis/sproutcore-rest-api-the-definitive-guide SproutCore]
* [http://code.google.com/p/grassyknoll/ Grassy Knoll] (Python)

rest/json

2008-09-04T16:31:23Z

DrErnie: == Issues ==

rest/json

2008-09-04T16:21:45Z

DrErnie: /* Charter */

rest/json

2008-09-04T16:15:52Z

DrErnie: resources

DrErnie: /* File Formats */

= URL Conventions =

The recommended conventions for RESTful URLs are those used by [http://topfunky.com/clients/peepcode/REST-cheatsheet.pdf Ruby on Rails], as seen in [http://developer.37signals.com/highrise/ Highrise]. Following these conventions for both HTTP method names and URL construction will allow your application to be consumed by ActiveResource, Jester, and other RESTful clients. Note that Rails 1.x used ";edit" and ";new" in place of the simpler "/edit" and "/new" recommended going forward.

== Routing ==
The principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class.
For a collection named "people", the primary routes would be:

=== Operate on the Collection ===
;GET /people: return a list of all records
;GET /people/new: return a form for creating a new record
;POST /people: submit fields for creating a new record

=== Operate on a Record ===

;GET /people/1: return the first record
;DELETE /people/1: destroy the first record

;GET /people/1/edit: return a form to edit the first record
;PUT /people/1: submit fields for updating the first record

=== Follow a Relationship ===

;GET /people/1/friends: return the collection of friends associated with the first person
;GET /people/1/friends/1: return the first friend of that person

=== Invoke Custom Actions ===
It isn't always possible to map ''everything'' into Create-Retrieve-Update-Delete ([http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete CRUD]). Thus, there is also a syntax for specifying custom actions:
;POST /people/1/promote: run the "promote" action against the first record
These should be used sparingly, as they are unlikely to be supported by most clients.

== File Formats ==

Data types are extremely important in REST. While it is ideal to specify the appropriate mime-type, developers are encouraged to follow Rails in supporting extension-based typing, e.g.:

;GET /people/1: return the first record in HTML format
;GET /people/1.html: return the first record in HTML format
;GET /people/1.xml: return the first record in [http://en.wikipedia.org/wiki/XML XML] format
;GET /people/1.json: return the first record in [http://en.wikipedia.org/wiki/JSON JSON] format

While the JSON mapping should be trivially obvious, the best practice for XML is to:
# use the column name as the element name
# include an appropriate "type" field

See the [http://developer.37signals.com/highrise/reference.shtml Highrise reference] for an example of how this works in practice.

rest/urls

2007-09-27T22:44:34Z

DrErnie: /* File Formats */ example

= URL Conventions =

The recommended conventions for RESTful URLs are those used by [http://topfunky.com/clients/peepcode/REST-cheatsheet.pdf Ruby on Rails], as seen in [http://developer.37signals.com/highrise/ Highrise]. Following these conventions for both HTTP method names and URL construction will allow your application to be consumed by ActiveResource, Jester, and other RESTful clients. Note that Rails 1.x used ";edit" and ";new" in place of the simpler "/edit" and "/new" recommended going forward.

== Routing ==
The principal unit of operation is the "collection", which typically corresponds to a database table or (in Rails) an ActiveRecord class.
For a collection named "people", the primary routes would be:

=== Operate on the Collection ===
;GET /people: return a list of all records
;GET /people/new: return a form for creating a new record
;POST /people: submit fields for creating a new record

=== Operate on a Record ===

;GET /people/1: return the first record
;DELETE /people/1: destroy the first record

;GET /people/1/edit: return a form to edit the first record
;PUT /people/1: submit fields for updating the first record

=== Follow a Relationship ===

;GET /people/1/friends: return the collection of friends associated with the first person
;GET /people/1/friends/1: return the first friend of that person

=== Invoke Custom Actions ===
It isn't always possible to map ''everything'' into Create-Retrieve-Update-Delete ([http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete CRUD]). Thus, there is also a syntax for specifying custom actions:
;POST /people/1/promote: run the "promote" action against the first record
These should be used sparingly, as they are unlikely to be supported by most clients.

== File Formats ==

Data types are extremely important in REST. While it is ideal to specify the appropriate mime-type, developers are encouraged to follow Rails in supporting extension-based typing, e.g.:

;GET /people/1: return the first record in HTML format
;GET /people/1.html: return the first record in HTML format
;GET /people/1.xml: return the first record in [http://en.wikipedia.org/wiki/XML XML] format
;GET /people/1.json: return the first record in [http://en.wikipedia.org/wiki/JSON JSON] format

Best practice is to use the column name as the element name, include an appropriate "type" field, as in [http://developer.37signals.com/highrise/reference.shtml Highrise]: