companies-house-rest 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dbb8d4a36799069defbd9f3780cdacb28d7c063c
+  data.tar.gz: 136fef2b3f98e9b5eb31f71e0255b4e68f86f300
+SHA512:
+  metadata.gz: f1d9e4f856d027e7125c12b1a9d82a84689c61d1f9f3c07d52635b8d8ac1c78603cfc5c7efa2286a45055ea977a4db3f7943f2a7bb55badda297a2bf629d6810
+  data.tar.gz: 307932848e29ebab49d2f88a3c7de393846f102ab12b286dd5bae00d0e2dc6dfd6176b0b3383db9895f6a365399656f0fb8a202afc88333d3a48b0e1055d0bf3

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 GOCARDLESS LTD
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+# CompaniesHouse::Client
+
+This Gem implements an API client for the Companies House REST API. It can be
+used to look up information about companies registered in the United Kingdom.
+As of July 2016, this API is described by Companies House as a "beta service."
+More information about this free API can be found
+[on the Companies House API website](https://developer.companieshouse.gov.uk/api/docs/index.html).
+
+To interact the older [CompaniesHouse XML-based API](http://xmlgw.companieshouse.gov.uk/),
+see the gem [companies-house-gateway](https://github.com/gocardless/companies-house-gateway-ruby).
+(Monthly subscription [fees](http://xmlgw.companieshouse.gov.uk/CHDpriceList.shtml), and other fees, may apply.)
+
+Quick start:
+* Register an account via the `Sign In / Register` link
+[on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
+* Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications)
+* Put your API key in an environment variable (not in your code):
+
+``` shell
+export COMPANIES_HOUSE_API_KEY=YOUR_API_KEY_HERE
+
+```
+* Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest)
+* Create and use a client:
+
+``` ruby
+require 'companies_house/client'
+client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY'])
+profile = client.company('07495895')
+```
+
+
+## Overview
+This gem is meant to provide a simple synchronous API to look up company profile
+information and company officers. The data returned is parsed JSON.
+
+This gem provides information on companies by their Companies House company
+number. This "company number" is actually a string and should be treated as such.
+The string may consist solely of digits (including leading 0s) or begin with
+alphabetic characters such as `NI` or `SC`.
+
+## Authentication
+
+Using the Companies House REST API requires you to register an account
+[on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
+and [configure an API key](https://developer.companieshouse.gov.uk/developer/applications).
+Developers should read
+[the Companies House developer guidelines](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/developerGuidelines.html)
+before using this API, and will note that these guidelines contain several
+instructions regarding API keys:
+
+* Do not embed API keys in your code
+* Do not store API keys in your source tree
+* Restrict API key use by IP address and domain
+* **Regenerate your API keys regularly**
+* Delete API keys when no longer required
+
+## Client Initialization
+
+All requests to the API are made through a client object:
+
+```ruby
+require 'companies_house/client'
+client = CompaniesHouse::Client.new(config)
+```
+
+The client is configured by passing a hash to the constructor. The supported keys for this
+hash are:
+
+| Key         | Description |
+| ----------- | ----------- |
+| `:api_key`  | Required. The API key received after registration. |
+| `:endpoint` | Optional. Specifies the base URI for the API (e.g. if using a self-hosted version) |
+
+## Requests
+
+Once a client has been initialised, requests can be made to the API.
+Details of the available fields in the response are in the Companies House
+[documentation](https://developer.companieshouse.gov.uk/api/docs/index.html).
+The endpoints currently implemented by the gem are:
+
+| Client Method               | Endpoint                                | Description |
+| --------------------------- | --------------------------------------- | ----------- |
+| `.company(company_number)`  | `GET /company/:company_number`          | Retrieves a company profile. |
+| `.officers(company_number)` | `GET /company/:company_number/officers` | Retrieves a list of company officers. |
+
+### .company
+This method implements the [readCompanyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/readCompanyProfile.html)
+API and returns the full [companyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/companyProfile-resource.html)
+resource.
+
+### .officers
+This method implements the [officersList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList.html)
+API. It will make one or more requests against this API, as necessary, to obtain
+the full list of company officers. It returns only the values under the `items`
+key from the
+[officerList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList-resource.html)
+resource(s) which it reads.
+
+### Other API Methods
+While there are other resources exposed by the
+[Companies House API](https://developer.companieshouse.gov.uk/api/docs/index.html),
+this gem does not implement access to these resources at this time.
+
+## Error Handling
+If a request to the Companies House API encounters an HTTP status other than
+`200 OK`, it will raise an instance of `CompaniesHouse::APIError` instead of
+returning response data. The error will have the following fields:
+
+| Field      | Description |
+| ---------- | ----------- |
+| `response` | The Net::HTTP response object from the failed API call. |
+| `status`   | A string containing the response status code. |
+
+
+Certain API responses will raise an instance of a more specific subclass of
+`CompaniesHouse::APIError`:
+
+| Status | Error                                 | Description |
+| ------ | ------------------------------------- | ----------- |
+| 401    | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) |
+| 404    | `CompaniesHouse::NotFoundError`       | Not Found. (No record of the company is available.) |
+| 429    | `CompaniesHouse::RateLimitError`      | Application is being [rate limited](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/rateLimiting.html) |
+
+The client will not catch any other errors which may occur, such as
+errors involving  network connections (e.g. `Errno::ECONNRESET`).
+
+## Development
+
+This gem is configured for development using a `bundler` workflow.
+Tests are written using RSpec, and Rubocop is used to provide linting.
+Bug reports and pull requests are welcome on this project's
+[GitHub repository](https://github.com/gocardless/companies-house-ruby).
+
+To get started:
+
+``` shell
+bundle install --path vendor
+```
+
+
+To run all tests and Rubocop:
+
+```shell
+bundle exec rake
+```

data/companies-house-rest.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'companies_house/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "companies-house-rest"
+  spec.version       = CompaniesHouse::VERSION
+  spec.authors       = ["GoCardless Engineering"]
+  spec.email         = ["developers@gocardless.com"]
+  spec.license       = "MIT"
+
+  spec.summary       = %q{Look up UK company registration information}
+  spec.description   = %q{Client for the Companies House REST API. Provides company profiles and officer lists.}
+  spec.homepage      = "https://github.com/gocardless/companies-house-ruby"
+
+  spec.files         = `git ls-files -z lib/ *.gemspec LICENSE README.md`.split("\x0")
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.required_ruby_version = '~> 2.0'
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.5.0"
+  spec.add_development_dependency "rubocop", "~> 0.41.2"
+  spec.add_development_dependency "webmock", "~> 2.1.0"
+end

data/lib/companies-house.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'companies_house/client'
+require 'companies_house/api_error'
+require 'companies_house/not_found_error'
+require 'companies_house/authentication_error'
+require 'companies_house/rate_limit_error'
+
+module CompaniesHouse
+  # The module that contains all the classes implementing the API client
+end

data/lib/companies_house/api_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CompaniesHouse
+  # Represents any response from the API which is not a 200 OK
+  class APIError < StandardError
+    attr_reader :status, :response
+
+    def initialize(msg, response = nil)
+      if response
+        msg = "#{msg} - HTTP #{response.code}"
+        @status = response.code
+      end
+
+      super(msg)
+      @response = response
+    end
+  end
+end

data/lib/companies_house/authentication_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CompaniesHouse
+  # Specific error class for when an invalid API key is used to access the service
+  class AuthenticationError < APIError
+    def initialize(response = nil)
+      super("Invalid API key", response)
+    end
+  end
+end

data/lib/companies_house/client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+require 'companies_house/api_error'
+require 'companies_house/not_found_error'
+require 'companies_house/authentication_error'
+require 'companies_house/rate_limit_error'
+require 'net/http'
+require 'json'
+
+module CompaniesHouse
+  # This class connects to the Companies House API
+  # at https://api.companieshouse.gov.uk
+  class Client
+    ENDPOINT = 'https://api.companieshouse.gov.uk'
+
+    attr_reader :api_key, :endpoint
+
+    def initialize(config)
+      raise ArgumentError, 'Missing API key' unless config[:api_key]
+      @api_key = config[:api_key]
+      @endpoint = URI(config[:endpoint] || ENDPOINT)
+      raise ArgumentError, 'HTTP is not supported' if @endpoint.scheme != 'https'
+    end
+
+    def end_connection
+      @connection.finish if @connection && @connection.started?
+    end
+
+    def company(id)
+      request(id)
+    end
+
+    # The API endpoint for company officers is paginated, and not all of the officers may
+    # be returned in the first request. We deal with this by collating all the pages of
+    # results into one result set before returning them.
+    def officers(id)
+      items = []
+      offset = 0
+
+      loop do
+        page = request(id, '/officers', start_index: offset)
+        total = page['total_results']
+        new_items = page['items']
+        items += new_items
+        offset += new_items.count
+
+        break if items.count >= total
+      end
+
+      items
+    end
+
+    def connection
+      @connection ||= Net::HTTP.new(endpoint.host, endpoint.port).tap do |conn|
+        conn.use_ssl = true
+      end
+    end
+
+    private
+
+    def request(company_id, extra_path = '', params = {})
+      uri = URI.join(endpoint, 'company/', "#{company_id}#{extra_path}")
+      uri.query = URI.encode_www_form(params)
+
+      req = Net::HTTP::Get.new(uri)
+      req.basic_auth api_key, ''
+
+      response = connection.request req
+      parse(response, company_id)
+    end
+
+    def parse(response, company_id)
+      case response.code
+      when '200'
+        return JSON[response.body]
+      when '401'
+        raise CompaniesHouse::AuthenticationError, response
+      when '404'
+        raise CompaniesHouse::NotFoundError.new(company_id, response)
+      when '429'
+        raise CompaniesHouse::RateLimitError, response
+      else
+        raise CompaniesHouse::APIError.new("Unknown API response", response)
+      end
+    end
+  end
+end

data/lib/companies_house/not_found_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CompaniesHouse
+  # Specific error class for when a company cannot be found (for example, if the company
+  # number given is invaid)
+  class NotFoundError < APIError
+    def initialize(company_id = nil, response = nil)
+      super("Company #{company_id || 'nil'} not found", response)
+    end
+  end
+end

data/lib/companies_house/rate_limit_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CompaniesHouse
+  # Specific error class for when an invalid API key is used to access the service
+  class RateLimitError < APIError
+    def initialize(response = nil)
+      super("Rate limit exceeded", response)
+    end
+  end
+end

data/lib/companies_house/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CompaniesHouse
+  VERSION = '0.1.2'
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: companies-house-rest
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- GoCardless Engineering
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-07-29 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.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.5.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.41.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.41.2
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+description: Client for the Companies House REST API. Provides company profiles and
+  officer lists.
+email:
+- developers@gocardless.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- companies-house-rest.gemspec
+- lib/companies-house.rb
+- lib/companies_house/api_error.rb
+- lib/companies_house/authentication_error.rb
+- lib/companies_house/client.rb
+- lib/companies_house/not_found_error.rb
+- lib/companies_house/rate_limit_error.rb
+- lib/companies_house/version.rb
+homepage: https://github.com/gocardless/companies-house-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ~>
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14.1
+signing_key: 
+specification_version: 4
+summary: Look up UK company registration information
+test_files: []