Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

doc enhancement

  • Loading branch information...
commit 43e5aad071dabd0692b968425ebe1c49db725664 1 parent a550fb5
@theganyo authored
Showing with 52 additions and 26 deletions.
  1. +52 −26 README.md
View
78 README.md
@@ -5,27 +5,30 @@ REST API with minimal dependencies.
## Installation
-Add this line to your application's Gemfile:
+### Project
+Add the gem to your project's Gemfile:
gem 'usergrid_iron'
-And then execute:
+Then rebuild your bundle:
$ bundle
-Or install it yourself as:
+### Stand-alone script
+Just manually install the gem:
$ gem install usergrid_iron
## Usage
-### Not familiar with Usergrid / Apigee's App Services?
+### Prerequisite
+You'll want to be at least a little bit familiar with Usergrid / Apigee's App Services before you jump in here - but it easy and it's great! Start here:
-#### It's great stuff! Check it out, here:
+ App Services docs: <http://apigee.com/docs/usergrid/>
+ Open source stack: <https://github.com/apigee/usergrid-stack>
- Docs: <http://apigee.com/docs/usergrid/>
- Open source: <https://github.com/apigee/usergrid-stack>
+Awesome. Let's go!
### Getting started with the Usergrid_iron SDK is simple!
@@ -43,24 +46,40 @@ application = ''
username = ''
password = ''
+# create the base application resource
+# (this is a RestClient.resource)
application = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"
+
+# login (note: not required for sandbox)
application.login username, password
-# create and store a dog in the 'dogs' collection on the server
+# create and store a new dog on the server
+# (the "response" is an enhanced RestClient.response)
response = application.create_dog breed: 'Black Mouth Cur', name: 'Old Yeller'
-# let's get the dog from the response and grab its persistent id
+# the response has returned the entity data
+# response.entity wraps it in an easy-to-use object
dog = response.entity
+
+# it's persistent now, so it has a unique id
uuid = dog.uuid
-# let's retrieve a dog from the server by UUID
-same_dog = application['dogs'][uuid].entity
+# we can retrieve the dog by UUID using Hash syntax and calling get()
+# (all dogs are stored in the "dogs" collection)
+response = application["dogs"][uuid].get
+same_dog = response.entity
+
+# we could also retrieve the dog by name
+# we could also use path ('/') syntax instead of nested Hash
+# and we can even skip get() - entity() will do it for us
+same_dog = application["dogs/#{dog.name}"].entity
# is it our dog? well, he knows his name!
-puts "My dog's name is: #{same_dog.name}"
+# (and we can retrieve its values by dot or Hash)
+puts "My dog's name is: #{same_dog.name} and his breed is #{same_dog['breed']}"
```
-Well that was really easy.
+Well that was really easy. More comments than code! :)
#### Let's try something slightly more complex.
Let's say you've registered for an organization, but you don't have an application yet
@@ -78,7 +97,7 @@ you shouldn't need to do anything!)
password = 'test'
app_name = 'dog_sitter'
- ## first, let's get that setup out of the way ##
+ ## first, let's get that setup out of the way... ##
# get a management context & login the superuser
management = Usergrid::Management.new usergrid_api
@@ -91,37 +110,44 @@ you shouldn't need to do anything!)
# create an user for our application
new_application.create_user username: 'username', password: 'password'
-
- ## now we can play with the puppies! ##
-
# login to our new application as our new user
- application = Usergrid::Application.new "#{usergrid_api}/#{org_name}/#{app_name}"
+ application = organization.application app_name
application.login 'username', 'password'
+
+ ## now we can play with the puppies! ##
+
# we can start with our dog again
application.create_dog breed: 'Black Mouth Cur', name: 'Old Yeller'
- # but this time let's create several more dogs at once
+ # but this time let's create several more dogs all at once
application.create_dogs [
{ breed: 'Catalan sheepdog', name: 'Einstein' },
{ breed: 'Cocker Spaniel', name: 'Lady' },
{ breed: 'Mixed', name: 'Benji' }]
# retrieve all the dogs (well, the first 'page' anyway) and tell them hi!
+ # note: we're calling collection() instead of entity() because we have several
dogs = application['dogs'].collection
- dogs.each do |dog| # works just like an array
- puts "Hello, #{dog.name}!" # entities automatically have attributes
+
+ # you can iterate a collection just like an array
+ dogs.each do |dog|
+ puts "Hello, #{dog.name}!"
end
- # "Benji, come!"
- benji = dogs.query("select * where name = 'Benji'").entity # shortcut: entity() returns the first
+ # Let's get Benji ("Benji, come!"), but this time we'll retrieve by query
+ response = dogs.query "select * where name = 'Benji'"
+
+ # we could call "response.collection.first"
+ # but there's a shortcut: entity() will also return the first
+ benji = response.entity
- # modify Benji's attributes & save
+ # modify Benji's attributes & save to the server
benji.location = 'home' # use attribute access
- benji['breed'] = 'American Cocker Spaniel' # or access it like a Hash
+ benji['breed'] = 'American Cocker Spaniel' # or access attributes like a Hash
benji.save
- # query for the dogs that are home (should just be Benji)
+ # now query for the dogs that are home (should just be Benji)
dogs = application['dogs'].query("select * where location = 'home'").collection
if dogs.size == 1 && dogs.first.location == 'home'
puts "Benji's home!"
Please sign in to comment.
Something went wrong with that request. Please try again.