chjsonapi 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e93a21d70d4ccbde889354002123685c6b38afb6
+  data.tar.gz: 3ee907f4e75fb4c60aac551ef8ed4fff2802f51e
+SHA512:
+  metadata.gz: 2b79297eea78c3e5046b38888c408c12793de6b21f97e76a7759b95c738be1a44a35b1d635f0df6a5c32a114ea1397aeda840b5a448aeb814569091de137e267
+  data.tar.gz: 86e86b6e9aa8cb4f457f396d9daedc4846d031a970db778556dcf667911d9e254ab0f58dcd9a4913b3111278ba3868b11b6872cde149305a959f4ea8cb6d07e4

data/.gitignore

@@ -0,0 +1 @@
+api_key.txt

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in chjsonapi.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,39 @@
+PATH
+  remote: .
+  specs:
+    chjsonapi (0.3.2)
+      curb (~> 0.8)
+      json (~> 1.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    curb (0.8.8)
+    diff-lcs (1.2.5)
+    json (1.8.3)
+    rake (10.4.2)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.1)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.10)
+  chjsonapi!
+  rake (~> 10.0)
+  rspec (~> 3.3)
+
+BUNDLED WITH
+   1.10.6

data/README.md

@@ -0,0 +1,136 @@
+# ChJsonApi <br> Companies House JSON API Gem
+
+Ruby Gem to help make requests to <a href="https://developer.companieshouse.gov.uk/api/docs/" title="Companies House">Companies House</a> public API.
+
+Version 0.3.2
+ - Adding support for multiple keys.
+ 
+Version 0.3.1
+ - Changing exception thrown on Too Many Requests
+
+Version 0.3.0
+ - Handling "Too Many Requests" message (CH says that happens when 600 requests are sent in 5 minutes. Then the next requests have the HTTP status header of 429 Too Many Requests)
+
+Version 0.2.2:
+ - Refactoring
+ - Changing gem name
+
+Version 0.2.1:
+ - Removing CH Api key
+ - Changing version on Gemspec file
+
+Version 0.2.0:
+ - Changed basic API. No longer accepts a single String as parameter. A named hash must always be provided to the functions.
+ - Added optional parameters to the officers request.
+ - Created Company Filing
+ 
+
+Version 0.1.0:
+ - Created Company profile API call
+ - Created Company registered office API call
+ - Created Company officers API call
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'chjsonapi'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install chjsonapi
+
+## Usage
+
+###Require
+
+Add this line to files where the Gem will be used.
+
+```ruby
+require 'chjsonapi'
+```
+
+###Companies House API Key
+
+To use Companies House API, you need to configure an API Key, which you can obtain from <a target="_blank" href="https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/apikey_authorisation.html" title="Companies House Authentication API key"> their website</a>.
+
+Before making any requests, you need to initialise the Gem by calling
+
+```ruby
+ChJsonApi.init "YOUR_API_KEY"
+```
+
+Or, if you have more than one key available, you can initialise the Gem with an array of keys by calling
+
+```ruby
+ChJsonApi.init ["FIRST_KEY", "SECOND_KEY", ... , "LAST_KEY"]
+```
+
+###Querying for <a target="_blank" href="https://developer.companieshouse.gov.uk/api/docs/company/company_number/readCompanyProfile.html" title="Company Profile">Company profile</a>
+
+```ruby
+json = ChJsonApi::Company.profile company_number:'COMPANY_NUMBER'
+puts json['company_number']
+```
+
+###Querying for <a target="_blank" href="https://developer.companieshouse.gov.uk/api/docs/company/company_number/registered-office-address/readRegisteredOfficeAddress.html" title="Company Registered Office Address">Company Registered Office Address</a>
+
+```ruby
+json = ChJsonApi::Company.registered_office company_number:'COMPANY_NUMBER'
+puts json['locality']
+```
+
+###Querying for <a target="_blank" href="https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList.html" title="Company Officers List">Company Officers List</a>
+
+```ruby
+json = ChJsonApi::Company.officers company_number:'COMPANY_NUMBER'
+puts json['items'][0]['address']['premises']
+```
+
+Or any of the optional parameters
+
+```ruby
+json = ChJsonApi::Company.officers company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,order_by:'ORDER_BY'
+puts json['items'][0]['address']['premises']
+```
+
+
+###Querying for a specific <a target="_blank" href="https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/transaction_id/getFilingHistoryItem.html" title="Filing History Item">Filing History Item</a>
+
+```ruby
+json = ChJsonApi::Company.filing_item company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,order_by:'ORDER_BY'
+puts json['transaction_id']
+```
+
+
+###Querying for <a target="_blank" href="https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/getFilingHistoryList.html" title="Filing History List">Filing History</a>
+
+```ruby
+json = ChJsonApi::Company.filing_list company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,order_by:'ORDER_BY'
+puts json['transaction_id']
+```
+
+Or any of the optional parameters
+
+```ruby
+json = ChJsonApi::Company.officers company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,category:'ORDER_BY'
+puts json['transaction_id']
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` 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](https://rubygems.org).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "chjsonapi"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/chjsonapi.gemspec

@@ -0,0 +1,38 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'chjsonapi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "chjsonapi"
+  spec.version       = ChJsonApi::VERSION
+  spec.authors       = ["Matheus Serpellone"]
+  spec.email         = ["m.serpellone@gmail.com"]
+
+
+  spec.summary       = %q{Gem to assist on calls to Companies House JSON API}
+  spec.description   = %q{Companies House JSON API gem}
+  spec.homepage      = "https://github.com/inniaccounts/companies-house-json-api"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.3"
+
+  spec.add_dependency "curb", "~> 0.8"
+  spec.add_dependency "json", "~> 1.8"
+
+end

data/lib/chjsonapi.rb

@@ -0,0 +1,143 @@
+require "chjsonapi/version"
+require 'curb'
+require 'json'
+require_relative 'chjsonapi/company'
+
+# Base class for the CH Json Api
+# Can be used to make direct API calls to Companies House domain
+# The extended classes should implement specific methods to interface with api_call by providing the appropriate
+# URL handles, querystrings and request types
+class ChJsonApi
+
+
+
+  #Call this before using any other method
+  def self.init(key)
+    if key.is_a? Array
+      @key = key
+    elsif key.is_a? String
+      @key = [key]
+    else
+      raise 'Invalid Key Type. String or Array of Strings accepted only.'
+    end
+
+    @index = 0
+    @tries = 0
+    true
+  end
+
+
+  #Calls the Companies House API at the service specified by handler and with the optional parameters provided in query
+  def self.api_call(handler, query)
+
+    raise 'Uninitialised API. Call ChJsonApi.init(key) with your Companies House API key before running any requests' if !@key || @key.empty?
+
+    query = normalise_query(query)
+
+    result = execute_call(handler, query)
+
+    return extract_response(result.body_str)
+
+  end
+
+  def self.execute_call(handler, query)
+    @result ||= Curl::Easy.new
+
+    @result.url = "https://api.companieshouse.gov.uk/#{handler}#{query}"
+
+    @result.username        = "#{choose_key}:"
+    @result.http_auth_types = :basic
+
+    @result.perform
+
+    code = @result.response_code
+
+    #Detect any errors.
+    #If found, treat them and retry the function
+    #This will
+    if code == 401
+      handle_invalid_key(@result)
+      @result = execute_call(handler, query)
+    end
+
+    if code == 429
+      handle_too_many_requests(@result)
+      @result = execute_call(handler, query)
+    end
+
+    ##All ok, reset the "tries" counter and return the result
+    @tries = 0
+    @result
+  end
+
+  def self.extract_response(response)
+    return {} if response.empty?
+    json       = JSON.parse(response)
+
+    return json unless json['errors']
+
+    raise json['errors'][0].map { |key, value| "#{key}=>#{value}" }.join(' ')
+
+  end
+
+  #TODO accept a key => value hash
+  def self.normalise_query(query)
+    if !query
+      query = ''
+    elsif query.kind_of? Array
+      query = "?#{query.join '&'}"
+    elsif !query.kind_of? String
+      raise 'Query must be a string or an array with each element being a "key=value" string'
+    end
+    query
+  end
+
+
+  private
+  def self.choose_key
+    if @key.length > 0
+      @key[@index % @key.count]
+    else
+      raise 'No valid keys!'
+    end
+  end
+
+  def self.try_another_key
+    #try next key and increment the number of tries so far
+    #Increment to next key
+    @index ||= 0
+    @index += 1
+
+    #Increase number of tries
+    @tries ||= 0
+    @tries += 1
+
+    #If we have tried all keys, return false
+    continue?
+  end
+
+  def self.handle_invalid_key(result)
+    #Removes key from the array
+    @key.delete @key[@index]
+    if continue?
+      @tries += 1
+      return true
+    else
+      raise RuntimeError.new({message: 'Unauthorized. Please check your API keys.', request: result})
+    end
+  end
+
+  def self.continue?
+    #Check if we tried all keys.
+    @tries <= @key.count
+  end
+
+  def self.handle_too_many_requests(result)
+    #Too Many Requests, just switch to next key
+    unless try_another_key
+      raise RuntimeError.new({message: 'Too Many Requests', request: result})
+    end
+    true
+  end
+
+end

data/lib/chjsonapi/company.rb

@@ -0,0 +1,59 @@
+
+class ChJsonApi
+  #Subclass of CHJsonApi that handles requests about the Company
+  class Company
+
+    def self.profile(param_hash)
+      req, _ = validate_param_hash param_hash, [:company_number]
+      ChJsonApi.api_call("company/#{req[:company_number]}", nil)
+    end
+
+    def self.registered_office(param_hash)
+      req, _ = validate_param_hash param_hash, [:company_number]
+      ChJsonApi.api_call("company/#{req[:company_number]}/registered-office-address", nil)
+    end
+
+    def self.officers(param_hash)
+      req, opt = validate_param_hash param_hash, [:company_number], [:items_per_page,:start_index,:order_by]
+      ChJsonApi.api_call("company/#{req[:company_number]}/officers", opt)
+    end
+
+    def self.filing_item(param_hash)
+      req, _ = validate_param_hash param_hash, [:company_number, :transaction_id]
+      ChJsonApi.api_call("company/#{req[:company_number]}/filing-history/#{req[:transaction_id]}", nil)
+    end
+
+    def self.filing_list(param_hash)
+      req, opt = validate_param_hash param_hash, [:company_number], [:items_per_page,:start_index,:category]
+      ChJsonApi.api_call("company/#{req[:company_number]}/filing-history", opt)
+    end
+
+
+
+    def self.validate_param_hash(param_hash, required, optional=[])
+      if param_hash.kind_of? Hash
+
+        required_fields = {}
+        optional_fields = []
+        param_hash.each do |key, value|
+
+          valid_value = value.to_s.scan(/[^0-9a-zA-Z_\-=,]/).empty?
+          if (required.include? key) && valid_value
+            required_fields[key] = value
+            required.delete key
+          elsif (optional.include? key) && valid_value
+            optional_fields << "#{key}=#{value}"
+            optional.delete key
+          end
+
+        end
+
+        raise "Required fields not provided: #{required.to_s}" unless required.empty?
+
+        [required_fields, optional_fields]
+      end
+
+    end
+
+  end
+end

data/lib/chjsonapi/version.rb

@@ -0,0 +1,3 @@
+class ChJsonApi
+  VERSION = '0.3.2'
+end

data/tasks/rspec.rake

@@ -0,0 +1,4 @@
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color']
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: chjsonapi
+version: !ruby/object:Gem::Version
+  version: 0.3.2
+platform: ruby
+authors:
+- Matheus Serpellone
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-11-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: curb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: Companies House JSON API gem
+email:
+- m.serpellone@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- chjsonapi.gemspec
+- lib/chjsonapi.rb
+- lib/chjsonapi/company.rb
+- lib/chjsonapi/version.rb
+- tasks/rspec.rake
+homepage: https://github.com/inniaccounts/companies-house-json-api
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Gem to assist on calls to Companies House JSON API
+test_files: []
+has_rdoc: