Upkey::Helios::Client

This gem is the interface for the Upkey::Helios API, allowing Users to easily access the desired information.

Installation

Add this line to your application's Gemfile:

gem 'upkey-helios-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install upkey-helios-client

Usage

To use the app you must first set up your Client for this gem:

client = Upkey::Helios::Client.new({ 
    access_key: ACCESS_KEY, 
    helios_url: HELIOS_URL 
})

This will spin up a client with the necessary credentials and information needed to find and communicate with the Helios API. After this has been set up you can begin using the API by passing path information and parameters as necessary. Details on this are found below.

Basic Routes

The gem will determine the API endpoint you are trying to access by what path information you pass in the array. For example, to reach /api/students you would pass [{ students: nil }] as the path_info - and for /api/students/1 you would pass [{ students: 1 }].

Examples on the multiple approaches for all REST verbs are included below:

# Get Multiple
client.get([{ students: 1 }])

# Get Single
client.get([{ students: 1 }])

# Post New
client.post([{ students: 1 }], student_params)

# Patch/Put Single
client.patch([{ students: 1 }], student_params)
OR
client.put([{ students: 1 }], student_params)

# Delete Single
client.delete([{ students: 1 }])

Nested Routes

Nested routes work exactly like basic routes, only the path_info Array should contain information for all relevant parent information. For example with the route /api/students/1/attributes you will have the following:

# Get Multiple
client.get([{ students: 1 }, { attributes: nil }])

# Get Single
client.get([{ students: 1 }, { attributes: 1 }])

# Post New
client.post([{ students: 1 }, { attributes: nil }], attribute_params)

# Patch/Put Single
client.patch([{ students: 1 }, { attributes: 1 }], attribute_params)
OR
client.put([{ students: 1 }, { attributes: 1 }], attribute_params)

# Delete Single
client.delete([{ students: 1 }, { attributes: 1 }])

In this example { students: 1 } passes the student_id param and { attributes: 1 } passes the general id param.

Response

The beauty of this gem really comes down to the general, uniform response it will give from the API. It passes these responses in Upkey::Helios::Response objects that have the following properties:

# For /api/students/1/attributes

<Upkey::Helios::Response
    @contents: [Array of Attribute Objects],
    @raw_headers: { Header Information Hash },
    @status: Status Code Integer
>

You can then access parsed information by simply calling response.contents, response.status and response.raw_headers accordingly.

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. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/beupkey/upkey-helios-client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Upkey::Helios::Client project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.