Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A simple, low-level Ruby SDK to Apigee's App Services (aka Usergrid) REST API with minimal dependencies.
Tree: 6ba1410d54

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Usergrid_iron enables simple, low-level Ruby access to Apigee's App Services (aka Usergrid) REST API with minimal dependencies.


Add this line to your application's Gemfile:

gem 'usergrid_iron'

And then execute:

$ bundle

Or install it yourself as:

$ gem install usergrid_iron


  1. Not familiar with Usergrid / Apigee's App Services? It's great stuff! Check it out, here:

Docs: Open source:

  1. Getting started with the Usergrid_iron SDK is simple! Let's start with the basics. I'll assume you've already set up an organization, application, and user - just fill in your own values in the code below.
require 'usergrid_iron'

# fill in your values here!
usergrid_api = 'http://localhost:8080'
organization = ''
application = ''
username = ''
password = ''

application = "#{usergrid_api}/#{organization}/#{application}"
application.login username, password

# create and store a dog in the 'dogs' collection on the server
response = application.create_entity 'dogs', { breed: 'Black Mouth Cur', name: 'Old Yeller' }

# let's get the dog from the response and grab its persistent id
dog = response.entity
uuid = dog.uuid

# let's retrieve a dog from the server by UUID
same_dog = application['dogs'][uuid].entity

# is it our dog? well, he knows his name!
puts "My dog's name is: #{}"

That was really easy. So let's try something slightly more complex. Let's say we've registered for an organization, but we don't have an application yet (or want to create a new one to work on). No worries, just fill in your organization and superuser credentials below, and follow along! (Better yet: If you used the Usergrid launcher and let it initialize your database, you shouldn't need to do anything!)

  require 'usergrid_iron'

  usergrid_api = 'http://localhost:8080'
  org_name = 'test-organization'
  username = 'test'
  password = 'test'
  app_name = 'dog_sitter'

  ## first, let's get that setup out of the way ##

  # get a management context & login the superuser
  management = usergrid_api
  management.login username, password

  # get the organization context & create a new application
  organization = management.organization org_name
  new_application = organization.create_application app_name

  # create an user for our application
  new_application.create_user 'username', 'name', '', 'password'

  ## now we can play with the puppies! ##

  # login to our new application as our new user
  application = "#{usergrid_api}/#{org_name}/#{app_name}"
  application.login 'username', 'password'

  # we can start with our dog again
  application.create_entity 'dogs', { breed: 'Black Mouth Cur', name: 'Old Yeller' }

  # but this time let's create several more dogs at once
  application.create_entities '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!
  dogs = application['dogs'].collection
  dogs.each do |dog|                          # works just like an array
    puts "Hello, #{}!"                # entities automatically have attributes

  # "Benji, come!"
  benji = dogs.query("select * where name = 'Benji'").entity  # shortcut: entity will return the first in the collection

  # modify Benji's attributes & save
  benji.location = 'home'                     # use attribute access
  benji['breed'] = 'American Cocker Spaniel'  # or access it like a Hash

  # 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 == 'home'
    puts "Benji's home!"

Whew. That's enough for now. But looking for a specific feature? Check out the rspecs, there are examples of nearly everything!


We welcome your enhancements!

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Write some broken rspecs.
  4. Fix the rspecs with your new code.
  5. Commit your changes (git commit -am 'Added some feature')
  6. Push your changes to the upstream branch (git push origin my-new-feature)
  7. Create new Pull Request

We've got 100% rspec coverage and we're looking to keep it that way! In order to run the tests, check out the Usergrid open source project (, build, and launch it locally.

(Note: If you change your local Usergrid setting from the default, be sure to update usergrid_iron/spec/spec_settings.yaml to match.)


The following features are not currently implemented on the server:

  • delete organization
  • delete application
  • delete user


  • Copyright (c) 2012 Scott Ganyo *
  • Licensed under the Apache License, Version 2.0 (the "License");
  • you may not use the included files except in compliance with the License.
  • You may obtain a copy of the License at *
  • *
  • Unless required by applicable law or agreed to in writing, software
  • distributed under the License is distributed on an "AS IS" BASIS,
  • WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  • See the License for the specific language governing permissions and
  • limitations under the License.
Something went wrong with that request. Please try again.