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
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
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.
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.
'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.
The client has the full API implemented. Here are the methods.
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.followThe 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.
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).
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.
Bug reports and pull requests are welcome on GitHub at https://github.com/danielpclark/trav3.
The gem is available as open source under the terms of the MIT License.