Usergrid_iron enables simple, low-level Ruby access to Apigee's App Services (aka Usergrid) REST API with minimal dependencies.
Add the gem to your project's Gemfile:
gem 'usergrid_iron'
Then rebuild your bundle:
$ bundle
Just manually install the gem:
$ gem install usergrid_iron
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:
App Services docs: http://apigee.com/docs/usergrid/ Open source stack: https://github.com/apigee/usergrid-stack
Awesome. Let's go!
For this example, we‘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 = '' # 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 new dog on the server # (the "response" is an enhanced RestClient.response) response = application.create_dog breed: 'Black Mouth Cur', name: 'Old Yeller' # 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 # 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! # (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. More comments than code! :)
Let‘s say you’ve registered for an organization, but you 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::Management.new 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: 'username', password: 'password' # login to our new application as our new user 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 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 # you can iterate a collection just like an array dogs.each do |dog| puts "Hello, #{dog.name}!" end # 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 to the server benji.location = 'home' # use attribute access benji['breed'] = 'American Cocker Spaniel' # or access attributes like a Hash benji.save # 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!" end
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!
git checkout -b my-new-feature)git commit -am 'Added some feature')git push origin my-new-feature)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 (https://github.com/apigee/usergrid-stack), 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.)
collection.follow_cursor.eachApplication::create_user username, password, ..., use create_user username: 'user', password: 'password'The following features are not currently implemented on the server:
Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. the ASF licenses this file to You under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
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.