Permalink
Browse files

updating the documentation to use json by default

fixes #8
squashing - closes #11
  • Loading branch information...
1 parent c0c6b33 commit 88f236533499304d1755b68d71677b61f19d120f @sfaxon sfaxon committed Apr 15, 2012
Showing with 69 additions and 62 deletions.
  1. +47 −44 README.rdoc
  2. +21 −17 lib/active_resource/associations.rb
  3. +1 −1 lib/active_resource/base.rb
View
@@ -17,7 +17,7 @@ for ActiveResource::Base.
== Overview
Model classes are mapped to remote REST resources by Active Resource much the same way Active Record maps model classes to database
-tables. When a request is made to a remote resource, a REST XML request is generated, transmitted, and the result
+tables. When a request is made to a remote resource, a REST JSON request is generated, transmitted, and the result
received and serialized into a usable Ruby object.
== Download and installation
@@ -26,7 +26,11 @@ The latest version of Active Resource can be installed with RubyGems:
% [sudo] gem install activeresource
-Source code can be downloaded as part of the Rails project on GitHub
+Or added to a Gemfile:
+
+ gem 'activeresource', :require => 'active_resource'
+
+Source code can be downloaded on GitHub
* https://github.com/rails/activeresource/tree/master/activeresource
@@ -43,15 +47,15 @@ Now the Person class is REST enabled and can invoke REST services very similarly
life cycle methods that operate against a persistent store.
# Find a person with id = 1
- ryan = Person.find(1)
+ tyler = Person.find(1)
Person.exists?(1) # => true
As you can see, the methods are quite similar to Active Record's methods for dealing with database
records. But rather than dealing directly with a database record, you're dealing with HTTP resources (which may or may not be database records).
==== Protocol
-Active Resource is built on a standard XML format for requesting and submitting resources over HTTP. It mirrors the RESTful routing
+Active Resource is built on a standard JSON or XML format for requesting and submitting resources over HTTP. It mirrors the RESTful routing
built into Action Controller but will also work with any other REST service that properly implements the protocol.
REST uses HTTP, but unlike "typical" web applications, it makes use of all the verbs available in the HTTP specification:
@@ -65,108 +69,107 @@ for more general information on REST web services, see the article here[http://e
==== Find
-Find requests use the GET method and expect the XML form of whatever resource/resources is/are being requested. So,
-for a request for a single element, the XML of that item is expected in response:
+Find requests use the GET method and expect the JSON form of whatever resource/resources is/are being requested. So,
+for a request for a single element, the JSON of that item is expected in response:
# Expects a response of
#
- # <person><id type="integer">1</id><attribute1>value1</attribute1><attribute2>..</attribute2></person>
+ # {"id":1,"first":"Tyler","last":"Durden"}
#
- # for GET http://api.people.com:3000/people/1.xml
+ # for GET http://api.people.com:3000/people/1.json
#
- ryan = Person.find(1)
+ tyler = Person.find(1)
-The XML document that is received is used to build a new object of type Person, with each
-XML element becoming an attribute on the object.
+The JSON document that is received is used to build a new object of type Person, with each
+JSON element becoming an attribute on the object.
- ryan.is_a? Person # => true
- ryan.attribute1 # => 'value1'
+ tyler.is_a? Person # => true
+ tyler.last # => 'Durden'
Any complex element (one that contains other elements) becomes its own object:
# With this response:
+ # {"id":1,"first":"Tyler","address":{"street":"Paper St.","state":"CA"}}
#
- # <person><id>1</id><attribute1>value1</attribute1><complex><attribute2>value2</attribute2></complex></person>
- #
- # for GET http://api.people.com:3000/people/1.xml
+ # for GET http://api.people.com:3000/people/1.json
#
- ryan = Person.find(1)
- ryan.complex # => <Person::Complex::xxxxx>
- ryan.complex.attribute2 # => 'value2'
+ tyler = Person.find(1)
+ tyler.address # => <Person::Address::xxxxx>
+ tyler.address.street # => 'Paper St.'
Collections can also be requested in a similar fashion
# Expects a response of
#
- # <people type="array">
- # <person><id type="integer">1</id><first>Ryan</first></person>
- # <person><id type="integer">2</id><first>Jim</first></person>
- # </people>
+ # [
+ # {"id":1,"first":"Tyler","last":"Durden"},
+ # {"id":2,"first":"Tony","last":"Stark",}
+ # ]
#
- # for GET http://api.people.com:3000/people.xml
+ # for GET http://api.people.com:3000/people.json
#
people = Person.all
- people.first # => <Person::xxx 'first' => 'Ryan' ...>
- people.last # => <Person::xxx 'first' => 'Jim' ...>
+ people.first # => <Person::xxx 'first' => 'Tyler' ...>
+ people.last # => <Person::xxx 'first' => 'Tony' ...>
==== Create
-Creating a new resource submits the XML form of the resource as the body of the request and expects
+Creating a new resource submits the JSON form of the resource as the body of the request and expects
a 'Location' header in the response with the RESTful URL location of the newly created resource. The
id of the newly created resource is parsed out of the Location response header and automatically set
as the id of the ARes object.
- # <person><first>Ryan</first></person>
+ # {"person":{"first":"Tyler","last":"Durden"}}
#
# is submitted as the body on
#
- # POST http://api.people.com:3000/people.xml
+ # POST http://api.people.com:3000/people.json
#
# when save is called on a new Person object. An empty response is
# is expected with a 'Location' header value:
#
# Response (201): Location: http://api.people.com:3000/people/2
#
- ryan = Person.new(:first => 'Ryan')
- ryan.new? # => true
- ryan.save # => true
- ryan.new? # => false
- ryan.id # => 2
+ tyler = Person.new(:first => 'Tyler')
+ tyler.new? # => true
+ tyler.save # => true
+ tyler.new? # => false
+ tyler.id # => 2
==== Update
'save' is also used to update an existing resource and follows the same protocol as creating a resource
with the exception that no response headers are needed -- just an empty response when the update on the
server side was successful.
- # <person><first>Ryan</first></person>
+ # {"person":{"first":"Tyler"}}
#
# is submitted as the body on
#
- # PUT http://api.people.com:3000/people/1.xml
+ # PUT http://api.people.com:3000/people/1.json
#
# when save is called on an existing Person object. An empty response is
# is expected with code (204)
#
- ryan = Person.find(1)
- ryan.first # => 'Ryan'
- ryan.first = 'Rizzle'
- ryan.save # => true
+ tyler = Person.find(1)
+ tyler.first # => 'Tyler'
+ tyler.first = 'Tyson'
+ tyler.save # => true
==== Delete
Destruction of a resource can be invoked as a class and instance method of the resource.
# A request is made to
#
- # DELETE http://api.people.com:3000/people/1.xml
+ # DELETE http://api.people.com:3000/people/1.json
#
# for both of these forms. An empty response with
# is expected with response code (200)
#
- ryan = Person.find(1)
- ryan.destroy # => true
- ryan.exists? # => false
+ tyler = Person.find(1)
+ tyler.destroy # => true
+ tyler.exists? # => false
Person.delete(2) # => true
Person.exists?(2) # => false
@@ -17,15 +17,19 @@ module Builder
# be used for resolving the association class.
#
# ==== Example for [:class_name] - option
- # GET /posts/123.xml delivers following response body:
- # <post>
- # <title>ActiveResource now have associations</title>
- # <content> ... </content>
- # <comments>
- # <comment> ... </comment>
- # <comment> ... </comment>
- # </comments>
- # </post>
+ # GET /posts/123.json delivers following response body:
+ # {
+ # title: "ActiveResource now has associations",
+ # body: "Lorem Ipsum"
+ # comments: [
+ # {
+ # content: "..."
+ # },
+ # {
+ # content: "..."
+ # }
+ # ]
+ # }
# ====
#
# <tt>has_many :comments, :class_name => 'myblog/comment'</tt>
@@ -47,14 +51,14 @@ def has_many(name, options = {})
# be used for resolving the association class.
#
# ==== Example for [:class_name] - option
- # GET /posts/123.xml delivers following response body:
- # <post>
- # <title>ActiveResource now have associations</title>
- # <content> ... </content>
- # <author>
- # <name>caffeinatedBoys</name>
- # </author>
- # </post>
+ # GET /posts/1.json delivers following response body:
+ # {
+ # title: "ActiveResource now has associations",
+ # body: "Lorem Ipsum",
+ # author: {
+ # name: "Gabby Blogger",
+ # }
+ # }
# ====
#
# <tt>has_one :author, :class_name => 'myblog/author'</tt>
@@ -228,7 +228,7 @@ module ActiveResource
#
# Active Resource supports validations on resources and will return errors if any of these validations fail
# (e.g., "First name can not be blank" and so on). These types of errors are denoted in the response by
- # a response code of <tt>422</tt> and an XML or JSON representation of the validation errors. The save operation will
+ # a response code of <tt>422</tt> and an JSON or XML representation of the validation errors. The save operation will
# then fail (with a <tt>false</tt> return value) and the validation errors can be accessed on the resource in question.
#
# ryan = Person.find(1)

0 comments on commit 88f2365

Please sign in to comment.