rtx-api-client-ruby Build Status

Ruby Client for the RTX API.

Installation

Add this line to your application's Gemfile:

gem 'rtx-api'

Then bundle install to retrieve the latest gem:

bundle install

Environment Variables

By adding RTX_USER_EMAIL and RTX_USER_PASSWORD to your environment variables, the gem will be able to load them during initialization of the Ruby client.

If you using a different url for for the RTX API, you can set the RTX_API_URL environment variable to use the appropriate one.

Testing locally

In order to test changes to your gem without having to release, you can update the Gemfile to point to the local version of the Gem

gem 'rtx-api', require: 'rtx/api', path: '../rtx-api-client-ruby'

Releasing new version

We have a higher expectation of testing in this repo than others due to the lower volume of releases and nature of the product. When you are submitting your PR, take a more conservative approach to testing and make sure you are adding tests for all new/changed methods.

Bump the version of the gem within ./lib/rtx/api/version.rb based on the changes you've made. Once your changes have been merged into master, you can release updated version of your gem. In order to release, you will need to be an owner of the RubyGems project and need to have your API credentials setup in your bash profile. Once complete, run the following command release command. 

bundle exec rake release

Usage

The client is lazily loaded, which means it will not authenticate until you make your initial request. Once the request is performed, we'll store the information for future requests. You will want to use the same instance of the client to perform all of your requests.

Initialization of the Client

Based on if you have your environment variables for RTX_USER_EMAIL and RTX_USER_PASSWORD configured

  client = RTX::API::Client.new

If you do not have your environment variables setup

client = RTX::API::Client.new("[email protected]", "your_password")

Logging Out

The client is authenticated once requests are made. After you are done with all of your requests, you can log out of your session. You should do this at the end regardless if you know you have made a request. It will not logout unless a token has been received.

  client.logout

Get Reviews

Using the initialized client, you can request reviews

# Creates the query
reviews = client.reviews

# Performs the request
reviews.data

# Metadata for the response can be retrieved
reviews.meta

If you want to add additional parameters to the query

# Creates the query
reviews = client.reviews(location_id: "56f2b386a97985e5a81e72f9", source_id: "56f2b386a97985e5a81e9td2")

# Performs the request
reviews.data

Get Notes

Using the initialized client, you can request notes

# Creates the query
notes = client.notes

# Performs the request
notes.data

# Metadata for the response can be retrieved
notes.meta

If you want to add additional parameters to the query

# Creates the query
notes = client.notes(review_id: "56f2b386a97985e5a81e72f9")

# Performs the request
notes.data

Pagination

If you want to add custom paging on the collection. The per_page and page method can be chained on to the query.

# Creates the query
reviews = client.reviews.per_page(50)

# Performs the request
reviews.data

If you want to get the next set of the collection

# Creates the query
reviews = client.reviews.per_page(50)

# Performs the request (For first 50)
reviews.data

# Next 50 of the collection (If available)
reviews.next.data

If you want to get a specific page from the collection

# Creates the query
reviews = client.reviews.per_page(50).page(10)

# Performs the request for 50 reviews from page 10
reviews.data

If you want to get the previous set of the collection

# Creates the query
reviews = client.reviews.per_page(50).page(10)

# Performs the request for 50 reviews from page 10
reviews.data

# Previous 50 of the collection from page 9
reviews.prev.data

If you want to know if there is a next page in the collection

# Creates the query
reviews = client.reviews.per_page(50).page(10)

# Performs the request for 50 reviews from page 10
reviews.data

# Returns true if there is another page in the collection
reviews.has_next?

If you want to know if there is a previous page in the collection

# Creates the query
reviews = client.reviews.per_page(50).page(2)

# Performs the request for 50 reviews from page 10
reviews.data

# Returns true if there is another page before it in the collection
reviews.has_previous?

Iterate all pages of a collection of resources

If you want to retrieve all pages of a collection starting at a specific page, you can pass a block into all_pages

# Creates the query
reviews = client.reviews.per_page(50)

# Performs the request for each page (at 50 per page) starting at page 2 and ending at the last page returning the page in the block
pages = []
reviews.all_pages(2) do |page|
  pages << page
end

Iterate all resources spanning all pages

If you want to retrieve all resources of a collection starting at a specific page, you can pass a block into all_resources

# Creates the query
reviews = client.reviews.per_page(50)

# Performs the request for each page starting at page 2 and ending at the last page returning the resource in the block
resources = []
reviews.all_resources(2) do |resource|
  resources << resource
end

Creating a Resource

The create! method will perform the create and return the new object

# Create a note
note = client.notes.create!(review_id: "56f2ad01565d61bb2a606329", location_id: "566c91337536e826ec8ebfa0", content: "This is my note!")

Resource Detail

The detail! method will perform a GET request that returns an object instead of an array

# Get a note
note = client.notes.detail!(id: "56f2ad01565d61bb2a606329", account_id: "566c91337536e826ec8ebfa0")

Updating a Resource

The update! method will perform the update via PUT and return the new object

# Update a review via PUT
review = client.reviews.update!(id: "56f2ad01565d61bb2a606329", summary: "Updated Summary Text")

The patch! method will perform the update via PATCH and return the new object

# Update a review via PATCH
review = client.reviews.patch!(id: "56f2ad01565d61bb2a606329", summary: "Updated Summary Text")

Deleting a Resource

The delete! method will perform the update and return true on success

# Delete a note
success = client.notes.delete!(id: "56f2bb805ee5d0bb2a9c6633")