Skip to content

Latest commit

 

History

History
196 lines (144 loc) · 9.23 KB

README.md

File metadata and controls

196 lines (144 loc) · 9.23 KB
Raw

Gem Version Build Status Maintainability Test Coverage Red The Docs Feature Complete

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.