agX Platform API Client

Ruby client for accessing Proagrica's agX Platform APIs.

Installation

Add this line to your application's Gemfile:

gem 'agx'

And then execute:

$ bundle

Or install it yourself as:

$ gem install agx

Usage

agX Content API

Setup agX Content Client (OAuth 2 Client Credentials Flow)

@agx_content_client = Agx::Content::Client.new(
  client_id: "your_client_id",
  client_secret: "your_client_secret",
  version: "v1"  # optional
  prod: true # optional, false for QA
  access_token: "token_if_stored", # optional
  expires_at: "token_expires_at_if_stored" # optional
)

Make get requests for Content API resources

# @agx_content_client.get("ResourceName", params_hash)
# => 'parsed_json_response_body'

crops = @agx_content_client.get("Crop")

# Passing in publishDate as param
weeds = @agx_content_client.get("Weed", {publishDate: date.to_s})

agX Sync API

Setup agX Sync Client (OAuth 2.0 / OpenID Connect 1.0 Authorization Code Flow)

This requires that you have already previously authenticated and authorized a user to agX with required scopes through the authorization code grant flow process and have persisted their sync ID, access token, refresh token, and access token expiration timestamp.

@agx_sync_client = Agx::Sync::Client.new(
  client_id: "your_client_id",
  client_secret: "your_client_secret",
  version: "v4",  # optional
  sync_id: "agx_user_sync_id",
  access_token: "agx_user_agx_token",
  refresh_token: "agx_user_refresh_token",
  token_expires_at: "access_token_expiration_timestamp",
  transaction_id: "agx_user_previous_transaction_id", # optional
  prod: true # optional, false for QA
)

Initiate a sync transaction, make Sync API requests, and end transaction

# To make calls without starting a transaction for resources that don't
# require it, use the get_nt method (GET only requests don't need transactions)
# @agx_sync_client.get_nt("Resource", start_time)
# => 'parsed_json_response_body'
growers = @agx_sync_client.get_nt("Grower")

# To make calls that require transactions (sync locking), call start_transaction
# and then use the get method to call for the resource. You should persist
# transaction ID per user until transaction is successfully ended by call
# to end_transaction
transaction_id = @agx_sync_client.start_transaction

# @agx_sync_client.get("Resource", start_time)
# => 'parsed_json_response_body'
growers = @agx_sync_client.get("Grower")

# Get all farms accessible for a grower
farms = @agx_sync_client.get("Grower/#{grower.guid}/Farm")

# Get all server changes on farms accessible for a grower since start_time
farms = @agx_sync_client.get("Grower/#{grower.guid}/Farm", last_sync_date.to_s)

# Put (insert) a new Grower
now = Time.now.utc
new_grower = {
  "SyncID": @agx_sync_client.sync_id,
  "ID": SecureRandom.uuid,
  "Name": "MYNEWGROWER",
  "ModifiedOn": now,
  "CreatedOn": now,
  "CreatorID": @agx_sync_client.sync_id,
  "EditorID": @agx_sync_client.sync_id,
  "SchemaVersion": "4.0"
}

@client.put("Grower", new_grower.to_json)

# etc...

@agx_sync_client.end_transaction

# clear the persisted transaction ID for user after ending sync transaction
user_transaction_id = nil

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/beaorn/agx-ruby.

License

The gem is available as open source under the terms of the MIT License (see LICENSE.txt)

agX is a registered trademark of Proagrica.