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 github.com/danielpclark/trav3.

License

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