Trav3

A simple abstraction layer for Travis CI API v3.

The benefits of this library over the official gem are:

No gem dependencies
Designed much like the API documentation
Handling the returned data is the same for nearly every response
Little to no learning curve

Installation

Add this line to your application's Gemfile:

gem 'trav3', '~> 1.0.0'

And then execute:

$ bundle

Or install it yourself as:

$ gem install trav3

Usage

You can get started with the following.

require 'trav3'
project = Trav3::Travis.new("name/example")

When you instantiate an instance of Trav3::Travis you get some default headers and default options.

Default Options

limit: 25 — for limiting data queries to 25 items at most

Options can be changed via the #options getter method which will give you a Trav3::Options instance. All changes to it affect the options that the Trav3::Travis instance will submit in url requests.

Default Headers

'Content-Type': 'application/json'
'Accept': 'application/json'
'Travis-API-Version': 3

Headers can be changed via the #headers getter method which will give you a Trav3::Headers instance. All changes to it affect the headers that the Trav3::Travis instance will submit in url requests.

API

The client has the full API implemented. Here are the methods.


`#active`	`#beta_feature`	`#beta_features`
`#branch`	`#branches`	`#broadcasts`
`#build`	`#builds`	`#build_jobs`
`#caches`	`#cron`	`#crons`
`#email_resubscribe`	`#email_unsubscribe`	`#env_var`
`#env_vars`	`#installation`	`#job`
`#key_pair`	`#key_pair_generated`	`#lint`
`#log`	`#messages`	`#organization`
`#organizations`	`#owner`	`#preference`
`#preferences`	`#repositories`	`#repository`
`#request`	`#requests`	`#stages`
`#setting`	`#settings`	`#user`

General Usage

project.owner
project.owner("owner")
project.repositories
project.repositories("owner")
project.repository
project.repository("owner/repo")
project.builds
project.build(12345)
project.build_jobs(12345)
project.job(1234)
project.log(1234)

# API Request Options
project.options.build({limit: 25})

# Pagination
builds = project.builds
builds.page.next
builds.page.first
builds.page.last

# Recommended inspection
builds.keys
builds.dig("some_key")

# Follow `@href`
repositories = project.repositories("owner")['repositories']
repositories.first.follow

Response

The results from queries return either Success or RequestError which both repsond with Hash like query methods for the JSON data or the Net::HTTP resonse object methods.

The Response classes Success and RequestError forward method calls for all of the instance methods of a ResponseCollection to the collection. And for the actual Net::HTTP response the following methods are forwarded from these classes to it:

#code
#code_type
#uri
#message
#read_header
#header
#value
#entity
#response
#body
#decode_content
#msg
#reading_body
#read_body
#http_version
#connection_close?
#connection_keep_alive?
#initialize_http_header
#get_fields
#each_header

The keys for the response are displayed with #inspect along with the object. Opening up any of the items from its key will produce a ResponseCollection object that behaves like both an Array or Hash and has a method to follow response links.

ResponseCollection uniformly implements:

#[]
#dig
#each
#fetch
#first
#follow
#hash?
#last
#warnings

Which each behave as they would on the collection type per collection type, Hash or Array, with the exception of #each. #each will wrap every item in an Array with another ResponseCollection, but if it's a Hash then #each simply works as it normally would on a Hash

ResponseCollection also forwards:

#count
#keys
#values
#has_key?
#key?
empty?

to the inner collection.

Follow

Each request returns a Response type of either Success or RequestError. When you have an instance of Success each response collection of either Hash or Array will be an instance of ResponseCollection. If the #hash? method responds as true the #follow method will follow any immediate @href link provided in the collection. If #hash? produces false then the collection is an Array of items and you may use the index of the item you want to follow the @href with; like so #follow(3).

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test 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/danielpclark/trav3.

License

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