companies-house-rest 0.4.4 → 0.4.5

Sign up to get free protection for your applications and to get access to all the features.
Files changed (17) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +20 -20
  3. data/README.md +159 -154
  4. data/companies-house-rest.gemspec +34 -34
  5. data/lib/companies_house.rb +11 -11
  6. data/lib/companies_house/api_error.rb +18 -18
  7. data/lib/companies_house/authentication_error.rb +10 -10
  8. data/lib/companies_house/bad_gateway_error.rb +10 -10
  9. data/lib/companies_house/client.rb +120 -105
  10. data/lib/companies_house/instrumentation/active_support.rb +9 -0
  11. data/lib/companies_house/instrumentation/null.rb +7 -0
  12. data/lib/companies_house/not_found_error.rb +14 -14
  13. data/lib/companies_house/rate_limit_error.rb +10 -10
  14. data/lib/companies_house/request.rb +99 -99
  15. data/lib/companies_house/timeout_error.rb +10 -10
  16. data/lib/companies_house/version.rb +5 -5
  17. metadata +18 -17
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: cd7dc68ed4f5ec30bd01f9bd3c98305af71c84b9a8ec0cfe94f36e126e6ac691
4
- data.tar.gz: d499188b852c72b801ccf32c13c04cb5ae6c71d22724d2ebd95940e5c172878d
3
+ metadata.gz: 697c77825563338b4cad1b54eb4f359fe248d877b8067adbbf6f85e8d43da776
4
+ data.tar.gz: 5ac0d3a4ba4003c3db8bea57765136e9356a40a5ee9cfe453b558ccc3358963a
5
5
  SHA512:
6
- metadata.gz: 02c0c1dcdc464cd7173a461aa443f417eb91fd9b1d030d41c643acea9f410ec4c3f223ac6b2f684836c6b89378c67dd3f729a04d9761c9a62517bca3e529eaa6
7
- data.tar.gz: 4a47367d243a9d2073814c7ca12a09705eefe7abd3b7661b15f421127980a81b9d214249ed3d8ee18e41b35d54fcffea88e775adc566c813e46ac681a51beaa2
6
+ metadata.gz: 29473c610f9dd6f2274d2d63eb0b773e7ad03ef4d1a1cfb90ef129d2ec9f63f787eec9e063de3e3060adea0dfda192cba3df8ae8105f03fb9b7c7dd38f912373
7
+ data.tar.gz: b0b1978ee8f169d18f1ac8d12b7bcc075744b55e0330d8fb21c690408c7b2cabb16cc13666877b881e7630c397b6c0a891c2c3a08bd7af8a6d4d86a0605cc5a2
data/LICENSE CHANGED
@@ -1,20 +1,20 @@
1
- Copyright (c) 2016 GOCARDLESS LTD
2
-
3
- Permission is hereby granted, free of charge, to any person obtaining
4
- a copy of this software and associated documentation files (the
5
- "Software"), to deal in the Software without restriction, including
6
- without limitation the rights to use, copy, modify, merge, publish,
7
- distribute, sublicense, and/or sell copies of the Software, and to
8
- permit persons to whom the Software is furnished to do so, subject to
9
- the following conditions:
10
-
11
- The above copyright notice and this permission notice shall be
12
- included in all copies or substantial portions of the Software.
13
-
14
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1
+ Copyright (c) 2016 GOCARDLESS LTD
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md CHANGED
@@ -1,154 +1,159 @@
1
- # CompaniesHouse::Client
2
-
3
- [![CircleCI](https://circleci.com/gh/gocardless/companies-house-rest.svg?style=svg)](https://circleci.com/gh/gocardless/companies-house-rest)
4
-
5
- This Gem implements an API client for the Companies House REST API. It can be
6
- used to look up information about companies registered in the United Kingdom.
7
- As of July 2016, this API is described by Companies House as a "beta service."
8
- More information about this free API can be found
9
- [on the Companies House API website](https://developer.companieshouse.gov.uk/api/docs/index.html).
10
-
11
- To interact the older [CompaniesHouse XML-based API](http://xmlgw.companieshouse.gov.uk/),
12
- see the gem [companies-house-gateway](https://github.com/gocardless/companies-house-gateway-ruby).
13
- (Monthly subscription [fees](http://xmlgw.companieshouse.gov.uk/CHDpriceList.shtml), and other fees, may apply.)
14
-
15
- Quick start:
16
- * Register an account via the `Sign In / Register` link
17
- [on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
18
- * Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications)
19
- * Put your API key in an environment variable (not in your code):
20
-
21
- ``` shell
22
- export COMPANIES_HOUSE_API_KEY=YOUR_API_KEY_HERE
23
-
24
- ```
25
- * Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest)
26
- * Create and use a client:
27
-
28
- ``` ruby
29
- require 'companies_house/client'
30
- client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY'])
31
- profile = client.company('07495895')
32
- ```
33
-
34
-
35
- ## Overview
36
- This gem is meant to provide a simple synchronous API to look up company profile
37
- information and company officers. The data returned is parsed JSON.
38
-
39
- This gem provides information on companies by their Companies House company
40
- number. This "company number" is actually a string and should be treated as such.
41
- The string may consist solely of digits (including leading 0s) or begin with
42
- alphabetic characters such as `NI` or `SC`.
43
-
44
- ## Authentication
45
-
46
- Using the Companies House REST API requires you to register an account
47
- [on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
48
- and [configure an API key](https://developer.companieshouse.gov.uk/developer/applications).
49
- Developers should read
50
- [the Companies House developer guidelines](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/developerGuidelines.html)
51
- before using this API, and will note that these guidelines contain several
52
- instructions regarding API keys:
53
-
54
- * Do not embed API keys in your code
55
- * Do not store API keys in your source tree
56
- * Restrict API key use by IP address and domain
57
- * **Regenerate your API keys regularly**
58
- * Delete API keys when no longer required
59
-
60
- ## Client Initialization
61
-
62
- All requests to the API are made through a client object:
63
-
64
- ```ruby
65
- require 'companies_house/client'
66
- client = CompaniesHouse::Client.new(config)
67
- ```
68
-
69
- The client is configured by passing a hash to the constructor. The supported keys for this
70
- hash are:
71
-
72
- | Key | Description |
73
- | ----------- | ----------- |
74
- | `:api_key` | Required. The API key received after registration. |
75
- | `:endpoint` | Optional. Specifies the base URI for the API (e.g. if using a self-hosted version) |
76
-
77
- ## Requests
78
-
79
- Once a client has been initialised, requests can be made to the API.
80
- Details of the available fields in the response are in the Companies House
81
- [documentation](https://developer.companieshouse.gov.uk/api/docs/index.html).
82
- The endpoints currently implemented by the gem are:
83
-
84
- | Client Method | Endpoint | Description |
85
- | --------------------------------------------------------------- | --------------------------------------- | ----------- |
86
- | `.company(company_number)` | `GET /company/:company_number` | Retrieves a company profile. |
87
- | `.officers(company_number)` | `GET /company/:company_number/officers` | Retrieves a list of company officers. |
88
- | `.company_search(query, items_per_page: nil, start_index: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. |
89
-
90
- ### .company
91
- This method implements the [readCompanyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/readCompanyProfile.html)
92
- API and returns the full [companyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/companyProfile-resource.html)
93
- resource.
94
-
95
- ### .officers
96
- This method implements the [officersList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList.html)
97
- API. It will make one or more requests against this API, as necessary, to obtain
98
- the full list of company officers. It returns only the values under the `items`
99
- key from the
100
- [officerList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList-resource.html)
101
- resource(s) which it reads.
102
-
103
- ### .company_search
104
- This method implements the [searchCompanies](https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html)
105
- API and returns the list of [companySearch](https://developer.companieshouse.gov.uk/api/docs/search-overview/CompanySearch-resource.html)
106
- resources that match the given query. The `items_per_page` and `start_index` parameters are optional.
107
-
108
- ### Other API Methods
109
- While there are other resources exposed by the
110
- [Companies House API](https://developer.companieshouse.gov.uk/api/docs/index.html),
111
- this gem does not implement access to these resources at this time.
112
-
113
- ## Error Handling
114
- If a request to the Companies House API encounters an HTTP status other than
115
- `200 OK`, it will raise an instance of `CompaniesHouse::APIError` instead of
116
- returning response data. The error will have the following fields:
117
-
118
- | Field | Description |
119
- | ---------- | ----------- |
120
- | `response` | The Net::HTTP response object from the failed API call. |
121
- | `status` | A string containing the response status code. |
122
-
123
-
124
- Certain API responses will raise an instance of a more specific subclass of
125
- `CompaniesHouse::APIError`:
126
-
127
- | Status | Error | Description |
128
- | ------ | ------------------------------------- | ----------- |
129
- | 401 | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) |
130
- | 404 | `CompaniesHouse::NotFoundError` | Not Found. (No record of the company is available.) |
131
- | 429 | `CompaniesHouse::RateLimitError` | Application is being [rate limited](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/rateLimiting.html) |
132
-
133
- The client will not catch any other errors which may occur, such as
134
- errors involving network connections (e.g. `Errno::ECONNRESET`).
135
-
136
- ## Development
137
-
138
- This gem is configured for development using a `bundler` workflow.
139
- Tests are written using RSpec, and Rubocop is used to provide linting.
140
- Bug reports and pull requests are welcome on this project's
141
- [GitHub repository](https://github.com/gocardless/companies-house-rest).
142
-
143
- To get started:
144
-
145
- ``` shell
146
- bundle install --path vendor
147
- ```
148
-
149
-
150
- To run all tests and Rubocop:
151
-
152
- ```shell
153
- bundle exec rake
154
- ```
1
+ # CompaniesHouse::Client
2
+
3
+ [![CircleCI](https://circleci.com/gh/gocardless/companies-house-rest.svg?style=svg)](https://circleci.com/gh/gocardless/companies-house-rest)
4
+
5
+ This Gem implements an API client for the Companies House REST API. It can be
6
+ used to look up information about companies registered in the United Kingdom.
7
+ As of July 2016, this API is described by Companies House as a "beta service."
8
+ More information about this free API can be found
9
+ [on the Companies House API website](https://developer.companieshouse.gov.uk/api/docs/index.html).
10
+
11
+ To interact the older [CompaniesHouse XML-based API](http://xmlgw.companieshouse.gov.uk/),
12
+ see the gem [companies-house-gateway](https://github.com/gocardless/companies-house-gateway-ruby).
13
+ (Monthly subscription [fees](http://xmlgw.companieshouse.gov.uk/CHDpriceList.shtml), and other fees, may apply.)
14
+
15
+ Quick start:
16
+ * Register an account via the `Sign In / Register` link
17
+ [on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
18
+ * Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications)
19
+ * Put your API key in an environment variable (not in your code):
20
+
21
+ ``` shell
22
+ export COMPANIES_HOUSE_API_KEY=YOUR_API_KEY_HERE
23
+
24
+ ```
25
+ * Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest)
26
+ * Create and use a client:
27
+
28
+ ``` ruby
29
+ require 'companies_house/client'
30
+ client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY'])
31
+ profile = client.company('07495895')
32
+ ```
33
+
34
+
35
+ ## Overview
36
+ This gem is meant to provide a simple synchronous API to look up company profile
37
+ information and company officers. The data returned is parsed JSON.
38
+
39
+ This gem provides information on companies by their Companies House company
40
+ number. This "company number" is actually a string and should be treated as such.
41
+ The string may consist solely of digits (including leading 0s) or begin with
42
+ alphabetic characters such as `NI` or `SC`.
43
+
44
+ ## Authentication
45
+
46
+ Using the Companies House REST API requires you to register an account
47
+ [on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
48
+ and [configure an API key](https://developer.companieshouse.gov.uk/developer/applications).
49
+ Developers should read
50
+ [the Companies House developer guidelines](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/developerGuidelines.html)
51
+ before using this API, and will note that these guidelines contain several
52
+ instructions regarding API keys:
53
+
54
+ * Do not embed API keys in your code
55
+ * Do not store API keys in your source tree
56
+ * Restrict API key use by IP address and domain
57
+ * **Regenerate your API keys regularly**
58
+ * Delete API keys when no longer required
59
+
60
+ ## Client Initialization
61
+
62
+ All requests to the API are made through a client object:
63
+
64
+ ```ruby
65
+ require 'companies_house/client'
66
+ client = CompaniesHouse::Client.new(config)
67
+ ```
68
+
69
+ The client is configured by passing a hash to the constructor. The supported keys for this
70
+ hash are:
71
+
72
+ | Key | Description |
73
+ | ------------------ | ----------- |
74
+ | `:api_key` | Required. The API key received after registration. |
75
+ | `:endpoint` | Optional. Specifies the base URI for the API (e.g. if using a self-hosted version) |
76
+ | `:instrumentation` | Optional. Instruments the request/response (see Instrumentation for details) |
77
+
78
+ ## Instrumentation
79
+ By default, no instrumentation is being applied.
80
+ If you are using Rails or the `ActiveSupport` gem, instrumentation will happen automatically via ![ActiveSupport::Notifications](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html)
81
+
82
+ ## Requests
83
+
84
+ Once a client has been initialised, requests can be made to the API.
85
+ Details of the available fields in the response are in the Companies House
86
+ [documentation](https://developer.companieshouse.gov.uk/api/docs/index.html).
87
+ The endpoints currently implemented by the gem are:
88
+
89
+ | Client Method | Endpoint | Description |
90
+ | --------------------------------------------------------------- | --------------------------------------- | ----------- |
91
+ | `.company(company_number)` | `GET /company/:company_number` | Retrieves a company profile. |
92
+ | `.officers(company_number)` | `GET /company/:company_number/officers` | Retrieves a list of company officers. |
93
+ | `.company_search(query, items_per_page: nil, start_index: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. |
94
+
95
+ ### .company
96
+ This method implements the [readCompanyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/readCompanyProfile.html)
97
+ API and returns the full [companyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/companyProfile-resource.html)
98
+ resource.
99
+
100
+ ### .officers
101
+ This method implements the [officersList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList.html)
102
+ API. It will make one or more requests against this API, as necessary, to obtain
103
+ the full list of company officers. It returns only the values under the `items`
104
+ key from the
105
+ [officerList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList-resource.html)
106
+ resource(s) which it reads.
107
+
108
+ ### .company_search
109
+ This method implements the [searchCompanies](https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html)
110
+ API and returns the list of [companySearch](https://developer.companieshouse.gov.uk/api/docs/search-overview/CompanySearch-resource.html)
111
+ resources that match the given query. The `items_per_page` and `start_index` parameters are optional.
112
+
113
+ ### Other API Methods
114
+ While there are other resources exposed by the
115
+ [Companies House API](https://developer.companieshouse.gov.uk/api/docs/index.html),
116
+ this gem does not implement access to these resources at this time.
117
+
118
+ ## Error Handling
119
+ If a request to the Companies House API encounters an HTTP status other than
120
+ `200 OK`, it will raise an instance of `CompaniesHouse::APIError` instead of
121
+ returning response data. The error will have the following fields:
122
+
123
+ | Field | Description |
124
+ | ---------- | ----------- |
125
+ | `response` | The Net::HTTP response object from the failed API call. |
126
+ | `status` | A string containing the response status code. |
127
+
128
+
129
+ Certain API responses will raise an instance of a more specific subclass of
130
+ `CompaniesHouse::APIError`:
131
+
132
+ | Status | Error | Description |
133
+ | ------ | ------------------------------------- | ----------- |
134
+ | 401 | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) |
135
+ | 404 | `CompaniesHouse::NotFoundError` | Not Found. (No record of the company is available.) |
136
+ | 429 | `CompaniesHouse::RateLimitError` | Application is being [rate limited](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/rateLimiting.html) |
137
+
138
+ The client will not catch any other errors which may occur, such as
139
+ errors involving network connections (e.g. `Errno::ECONNRESET`).
140
+
141
+ ## Development
142
+
143
+ This gem is configured for development using a `bundler` workflow.
144
+ Tests are written using RSpec, and Rubocop is used to provide linting.
145
+ Bug reports and pull requests are welcome on this project's
146
+ [GitHub repository](https://github.com/gocardless/companies-house-rest).
147
+
148
+ To get started:
149
+
150
+ ``` shell
151
+ bundle install --path vendor
152
+ ```
153
+
154
+
155
+ To run all tests and Rubocop:
156
+
157
+ ```shell
158
+ bundle exec rake
159
+ ```
data/companies-house-rest.gemspec CHANGED
@@ -1,34 +1,34 @@
1
- # frozen_string_literal: true
2
-
3
- lib = File.expand_path("lib", __dir__)
4
- $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
5
- require "companies_house/version"
6
-
7
- Gem::Specification.new do |spec|
8
- spec.name = "companies-house-rest"
9
- spec.version = CompaniesHouse::VERSION
10
- spec.authors = ["GoCardless Engineering"]
11
- spec.email = ["developers@gocardless.com"]
12
- spec.license = "MIT"
13
-
14
- spec.summary = "Look up UK company registration information"
15
- spec.description = "Client for the Companies House REST API. Provides company " \
16
- "profiles and officer lists."
17
- spec.homepage = "https://github.com/gocardless/companies-house-rest"
18
-
19
- spec.files = `git ls-files -z lib/ *.gemspec LICENSE README.md`.split("\x0")
20
- spec.bindir = "exe"
21
- spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
22
- spec.require_paths = ["lib"]
23
- spec.required_ruby_version = ">= 2.5.1"
24
-
25
- spec.add_runtime_dependency "activesupport", ">= 4.2", "< 6"
26
- spec.add_runtime_dependency "virtus", "~> 1.0", ">= 1.0.5"
27
-
28
- spec.add_development_dependency "bundler", "~> 1.10"
29
- spec.add_development_dependency "gc_ruboconfig", "~> 2.3"
30
- spec.add_development_dependency "rake", "~> 12.0"
31
- spec.add_development_dependency "rspec", "~> 3.5"
32
- spec.add_development_dependency "timecop", "~> 0.8"
33
- spec.add_development_dependency "webmock", "~> 3.0"
34
- end
1
+ # frozen_string_literal: true
2
+
3
+ lib = File.expand_path("lib", __dir__)
4
+ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
5
+ require "companies_house/version"
6
+
7
+ Gem::Specification.new do |spec|
8
+ spec.name = "companies-house-rest"
9
+ spec.version = CompaniesHouse::VERSION
10
+ spec.authors = ["GoCardless Engineering"]
11
+ spec.email = ["developers@gocardless.com"]
12
+ spec.license = "MIT"
13
+
14
+ spec.summary = "Look up UK company registration information"
15
+ spec.description = "Client for the Companies House REST API. Provides company " \
16
+ "profiles and officer lists."
17
+ spec.homepage = "https://github.com/gocardless/companies-house-rest"
18
+
19
+ spec.files = `git ls-files -z lib/ *.gemspec LICENSE README.md`.split("\x0")
20
+ spec.bindir = "exe"
21
+ spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
22
+ spec.require_paths = ["lib"]
23
+ spec.required_ruby_version = ">= 2.5.5"
24
+
25
+ spec.add_runtime_dependency "activesupport", ">= 4.2", "< 6"
26
+ spec.add_runtime_dependency "virtus", "~> 1.0", ">= 1.0.5"
27
+
28
+ spec.add_development_dependency "gc_ruboconfig", "~> 2.4"
29
+ spec.add_development_dependency "rake", "~> 12.0"
30
+ spec.add_development_dependency "rspec", "~> 3.5"
31
+ spec.add_development_dependency "rspec_junit_formatter", "~> 0.4.1"
32
+ spec.add_development_dependency "timecop", "~> 0.8"
33
+ spec.add_development_dependency "webmock", "~> 3.0"
34
+ end
data/lib/companies_house.rb CHANGED
@@ -1,11 +1,11 @@
1
- # frozen_string_literal: true
2
-
3
- require "companies_house/client"
4
- require "companies_house/api_error"
5
- require "companies_house/not_found_error"
6
- require "companies_house/authentication_error"
7
- require "companies_house/rate_limit_error"
8
-
9
- module CompaniesHouse
10
- # The module that contains all the classes implementing the API client
11
- end
1
+ # frozen_string_literal: true
2
+
3
+ require "companies_house/client"
4
+ require "companies_house/api_error"
5
+ require "companies_house/not_found_error"
6
+ require "companies_house/authentication_error"
7
+ require "companies_house/rate_limit_error"
8
+
9
+ module CompaniesHouse
10
+ # The module that contains all the classes implementing the API client
11
+ end
data/lib/companies_house/api_error.rb CHANGED
@@ -1,18 +1,18 @@
1
- # frozen_string_literal: true
2
-
3
- module CompaniesHouse
4
- # Represents any response from the API which is not a 200 OK
5
- class APIError < StandardError
6
- attr_reader :status, :response
7
-
8
- def initialize(msg, response = nil)
9
- if response
10
- msg = "#{msg} - HTTP #{response.code}"
11
- @status = response.code
12
- end
13
-
14
- super(msg)
15
- @response = response
16
- end
17
- end
18
- end
1
+ # frozen_string_literal: true
2
+
3
+ module CompaniesHouse
4
+ # Represents any response from the API which is not a 200 OK
5
+ class APIError < StandardError
6
+ attr_reader :status, :response
7
+
8
+ def initialize(msg, response = nil)
9
+ if response
10
+ msg = "#{msg} - HTTP #{response.code}"
11
+ @status = response.code
12
+ end
13
+
14
+ super(msg)
15
+ @response = response
16
+ end
17
+ end
18
+ end
data/lib/companies_house/authentication_error.rb CHANGED
@@ -1,10 +1,10 @@
1
- # frozen_string_literal: true
2
-
3
- module CompaniesHouse
4
- # Specific error class for when an invalid API key is used to access the service
5
- class AuthenticationError < APIError
6
- def initialize(response = nil)
7
- super("Invalid API key", response)
8
- end
9
- end
10
- end
1
+ # frozen_string_literal: true
2
+
3
+ module CompaniesHouse
4
+ # Specific error class for when an invalid API key is used to access the service
5
+ class AuthenticationError < APIError
6
+ def initialize(response = nil)
7
+ super("Invalid API key", response)
8
+ end
9
+ end
10
+ end
data/lib/companies_house/bad_gateway_error.rb CHANGED
@@ -1,10 +1,10 @@
1
- # frozen_string_literal: true
2
-
3
- module CompaniesHouse
4
- # Raised when a request returned a 502
5
- class BadGatewayError < APIError
6
- def initialize(response = nil)
7
- super("Bad gateway error", response)
8
- end
9
- end
10
- end
1
+ # frozen_string_literal: true
2
+
3
+ module CompaniesHouse
4
+ # Raised when a request returned a 502
5
+ class BadGatewayError < APIError
6
+ def initialize(response = nil)
7
+ super("Bad gateway error", response)
8
+ end
9
+ end
10
+ end
data/lib/companies_house/client.rb CHANGED
@@ -1,105 +1,120 @@
1
- # frozen_string_literal: true
2
-
3
- require "companies_house/request"
4
- require "net/http"
5
-
6
- module CompaniesHouse
7
- # This class provides an interface to the Companies House API
8
- # at https://api.companieshouse.gov.uk.
9
- # Specifically, it manages the connections and arranges requests.
10
- class Client
11
- ENDPOINT = "https://api.companieshouse.gov.uk"
12
-
13
- attr_reader :api_key, :endpoint
14
-
15
- def initialize(config)
16
- raise ArgumentError, "Missing API key" unless config[:api_key]
17
-
18
- @api_key = config[:api_key]
19
- @endpoint = URI(config[:endpoint] || ENDPOINT)
20
- @open_timeout = config[:open_timeout] || 60
21
- @read_timeout = config[:read_timeout] || 60
22
- raise ArgumentError, "HTTP is not supported" if @endpoint.scheme != "https"
23
- end
24
-
25
- def end_connection
26
- @connection.finish if @connection&.started?
27
- end
28
-
29
- def company(id)
30
- request(:company, "company/#{id}", {}, make_transaction_id, id)
31
- end
32
-
33
- def officers(id)
34
- get_all_pages(:officers, "company/#{id}/officers", id)
35
- end
36
-
37
- def persons_with_significant_control(id, register_view: false)
38
- get_all_pages(
39
- :persons_with_significant_control,
40
- "company/#{id}/persons-with-significant-control",
41
- id,
42
- register_view: register_view,
43
- )
44
- end
45
-
46
- def company_search(query, items_per_page: nil, start_index: nil)
47
- request(
48
- :company_search,
49
- "search/companies",
50
- { q: query, items_per_page: items_per_page, start_index: start_index }.compact,
51
- )
52
- end
53
-
54
- def connection
55
- @connection ||= Net::HTTP.new(endpoint.host, endpoint.port).tap do |conn|
56
- conn.use_ssl = true
57
- conn.open_timeout = @open_timeout
58
- conn.read_timeout = @read_timeout
59
- end
60
- end
61
-
62
- private
63
-
64
- # Fetch and combine all pages of a paginated API call
65
- def get_all_pages(resource, path, id, query = {})
66
- items = []
67
- offset = 0
68
- xid = make_transaction_id
69
-
70
- loop do
71
- page = request(resource, path, query.merge(start_index: offset), xid, id)
72
- new_items = page["items"]
73
- total = page["total_results"] || new_items.count
74
-
75
- items += new_items
76
- offset += new_items.count
77
-
78
- break if items.count >= total
79
- end
80
-
81
- items
82
- end
83
-
84
- def make_transaction_id
85
- SecureRandom.hex(10)
86
- end
87
-
88
- def request(resource,
89
- path,
90
- params = {},
91
- transaction_id = make_transaction_id,
92
- resource_id = nil)
93
- Request.new(
94
- connection: connection,
95
- api_key: @api_key,
96
- endpoint: @endpoint,
97
- path: path,
98
- query: params,
99
- resource_type: resource,
100
- resource_id: resource_id,
101
- transaction_id: transaction_id,
102
- ).execute
103
- end
104
- end
105
- end
1
+ # frozen_string_literal: true
2
+
3
+ require "companies_house/request"
4
+ require "companies_house/instrumentation/null"
5
+ require "companies_house/instrumentation/active_support"
6
+ require "net/http"
7
+ require "securerandom"
8
+
9
+ module CompaniesHouse
10
+ # This class provides an interface to the Companies House API
11
+ # at https://api.companieshouse.gov.uk.
12
+ # Specifically, it manages the connections and arranges requests.
13
+ class Client
14
+ ENDPOINT = "https://api.companieshouse.gov.uk"
15
+
16
+ attr_reader :api_key, :endpoint, :instrumentation
17
+
18
+ def initialize(config)
19
+ raise ArgumentError, "Missing API key" unless config[:api_key]
20
+
21
+ @api_key = config[:api_key]
22
+ @endpoint = URI(config[:endpoint] || ENDPOINT)
23
+ @open_timeout = config[:open_timeout] || 60
24
+ @read_timeout = config[:read_timeout] || 60
25
+ @instrumentation = configure_instrumentation(config[:instrumentation])
26
+ raise ArgumentError, "HTTP is not supported" if @endpoint.scheme != "https"
27
+ end
28
+
29
+ def end_connection
30
+ @connection.finish if @connection&.started?
31
+ end
32
+
33
+ def company(id)
34
+ request(:company, "company/#{id}", {}, make_transaction_id, id)
35
+ end
36
+
37
+ def officers(id)
38
+ get_all_pages(:officers, "company/#{id}/officers", id)
39
+ end
40
+
41
+ def persons_with_significant_control(id, register_view: false)
42
+ get_all_pages(
43
+ :persons_with_significant_control,
44
+ "company/#{id}/persons-with-significant-control",
45
+ id,
46
+ register_view: register_view,
47
+ )
48
+ end
49
+
50
+ def company_search(query, items_per_page: nil, start_index: nil)
51
+ request(
52
+ :company_search,
53
+ "search/companies",
54
+ { q: query, items_per_page: items_per_page, start_index: start_index }.compact,
55
+ )
56
+ end
57
+
58
+ def connection
59
+ @connection ||= Net::HTTP.new(endpoint.host, endpoint.port).tap do |conn|
60
+ conn.use_ssl = true
61
+ conn.open_timeout = @open_timeout
62
+ conn.read_timeout = @read_timeout
63
+ end
64
+ end
65
+
66
+ private
67
+
68
+ # Fetch and combine all pages of a paginated API call
69
+ def get_all_pages(resource, path, id, query = {})
70
+ items = []
71
+ offset = 0
72
+ xid = make_transaction_id
73
+
74
+ loop do
75
+ page = request(resource, path, query.merge(start_index: offset), xid, id)
76
+ new_items = page["items"]
77
+ total = page["total_results"] || new_items.count
78
+
79
+ items += new_items
80
+ offset += new_items.count
81
+
82
+ break if items.count >= total
83
+ end
84
+
85
+ items
86
+ end
87
+
88
+ def make_transaction_id
89
+ SecureRandom.hex(10)
90
+ end
91
+
92
+ def request(resource,
93
+ path,
94
+ params = {},
95
+ transaction_id = make_transaction_id,
96
+ resource_id = nil)
97
+ Request.new(
98
+ connection: connection,
99
+ api_key: @api_key,
100
+ endpoint: @endpoint,
101
+ path: path,
102
+ query: params,
103
+ resource_type: resource,
104
+ resource_id: resource_id,
105
+ transaction_id: transaction_id,
106
+ instrumentation: instrumentation,
107
+ ).execute
108
+ end
109
+
110
+ def configure_instrumentation(instrumentation)
111
+ return instrumentation unless instrumentation.nil?
112
+
113
+ if defined?(ActiveSupport::Notifications)
114
+ Instrumentation::ActiveSupport
115
+ else
116
+ Instrumentation::Null
117
+ end
118
+ end
119
+ end
120
+ end
data/lib/companies_house/instrumentation/active_support.rb ADDED
@@ -0,0 +1,9 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Instrumentation
4
+ class ActiveSupport
5
+ def self.publish(*args)
6
+ ::ActiveSupport::Notifications.publish(**args)
7
+ end
8
+ end
9
+ end
data/lib/companies_house/instrumentation/null.rb ADDED
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Instrumentation
4
+ class Null
5
+ def self.publish(*args); end
6
+ end
7
+ end
data/lib/companies_house/not_found_error.rb CHANGED
@@ -1,14 +1,14 @@
1
- # frozen_string_literal: true
2
-
3
- module CompaniesHouse
4
- # Specific error class for when a company cannot be found (for example, if the company
5
- # number given is invaid)
6
- class NotFoundError < APIError
7
- def initialize(resource_type, resource_id = nil, response = nil)
8
- super(
9
- "Resource not found - type `#{resource_type}`, id `#{resource_id || 'nil'}`",
10
- response,
11
- )
12
- end
13
- end
14
- end
1
+ # frozen_string_literal: true
2
+
3
+ module CompaniesHouse
4
+ # Specific error class for when a company cannot be found (for example, if the company
5
+ # number given is invaid)
6
+ class NotFoundError < APIError
7
+ def initialize(resource_type, resource_id = nil, response = nil)
8
+ super(
9
+ "Resource not found - type `#{resource_type}`, id `#{resource_id || 'nil'}`",
10
+ response,
11
+ )
12
+ end
13
+ end
14
+ end
data/lib/companies_house/rate_limit_error.rb CHANGED
@@ -1,10 +1,10 @@
1
- # frozen_string_literal: true
2
-
3
- module CompaniesHouse
4
- # Specific error class for when an invalid API key is used to access the service
5
- class RateLimitError < APIError
6
- def initialize(response = nil)
7
- super("Rate limit exceeded", response)
8
- end
9
- end
10
- end
1
+ # frozen_string_literal: true
2
+
3
+ module CompaniesHouse
4
+ # Specific error class for when an invalid API key is used to access the service
5
+ class RateLimitError < APIError
6
+ def initialize(response = nil)
7
+ super("Rate limit exceeded", response)
8
+ end
9
+ end
10
+ end
data/lib/companies_house/request.rb CHANGED
@@ -1,99 +1,99 @@
1
- # frozen_string_literal: true
2
-
3
- require "companies_house/api_error"
4
- require "companies_house/not_found_error"
5
- require "companies_house/authentication_error"
6
- require "companies_house/rate_limit_error"
7
- require "companies_house/timeout_error"
8
- require "companies_house/bad_gateway_error"
9
-
10
- require "virtus"
11
- require "uri"
12
- require "json"
13
-
14
- require "active_support/notifications"
15
-
16
- module CompaniesHouse
17
- # This class manages individual requests.
18
- # Users of the CompaniesHouse gem should not instantiate this class
19
- # and should instead use CompaniesHouse::Client.
20
- class Request
21
- include Virtus.model
22
- # API-level attributes
23
- attribute :connection, Net::HTTP, required: true
24
- attribute :api_key, String, required: true
25
- attribute :endpoint, URI, required: true
26
-
27
- # Physical request attributes
28
- attribute :path, String, required: true
29
- attribute :query, Hash, required: true
30
-
31
- # Logical request attributes
32
- attribute :resource_type, Symbol, required: true
33
- attribute :resource_id, String
34
-
35
- attribute :transaction_id, String, required: true
36
-
37
- def initialize(args)
38
- super(args)
39
-
40
- @uri = URI.join(endpoint, path)
41
- @uri.query = URI.encode_www_form(query)
42
-
43
- @notification_payload = {
44
- method: :get,
45
- path: path,
46
- query: query,
47
- }
48
- end
49
-
50
- def execute
51
- @started = Time.now.utc
52
-
53
- req = Net::HTTP::Get.new(@uri)
54
- req.basic_auth @api_key, ""
55
-
56
- response = connection.request req
57
- @notification_payload[:status] = response.code
58
-
59
- begin
60
- @notification_payload[:response] = parse(response, resource_type, resource_id)
61
- rescue StandardError => e
62
- @notification_payload[:error] = e
63
- raise e
64
- ensure
65
- publish_notification
66
- end
67
- rescue Net::OpenTimeout, Net::ReadTimeout
68
- raise TimeoutError
69
- end
70
-
71
- private
72
-
73
- def publish_notification
74
- ActiveSupport::Notifications.publish(
75
- "companies_house.#{resource_type}",
76
- @started, Time.now.utc,
77
- transaction_id,
78
- @notification_payload
79
- )
80
- end
81
-
82
- def parse(response, resource_type, resource_id)
83
- case response.code
84
- when "200"
85
- JSON[response.body]
86
- when "401"
87
- raise CompaniesHouse::AuthenticationError, response
88
- when "404"
89
- raise CompaniesHouse::NotFoundError.new(resource_type, resource_id, response)
90
- when "429"
91
- raise CompaniesHouse::RateLimitError, response
92
- when "502"
93
- raise CompaniesHouse::BadGatewayError, response
94
- else
95
- raise CompaniesHouse::APIError.new("Unknown API response", response)
96
- end
97
- end
98
- end
99
- end
1
+ # frozen_string_literal: true
2
+
3
+ require "companies_house/api_error"
4
+ require "companies_house/not_found_error"
5
+ require "companies_house/authentication_error"
6
+ require "companies_house/rate_limit_error"
7
+ require "companies_house/timeout_error"
8
+ require "companies_house/bad_gateway_error"
9
+
10
+ require "virtus"
11
+ require "uri"
12
+ require "json"
13
+
14
+ module CompaniesHouse
15
+ # This class manages individual requests.
16
+ # Users of the CompaniesHouse gem should not instantiate this class
17
+ # and should instead use CompaniesHouse::Client.
18
+ class Request
19
+ include Virtus.model
20
+ # API-level attributes
21
+ attribute :connection, Net::HTTP, required: true
22
+ attribute :api_key, String, required: true
23
+ attribute :endpoint, URI, required: true
24
+
25
+ # Physical request attributes
26
+ attribute :path, String, required: true
27
+ attribute :query, Hash, required: true
28
+
29
+ # Logical request attributes
30
+ attribute :resource_type, Symbol, required: true
31
+ attribute :resource_id, String
32
+
33
+ attribute :transaction_id, String, required: true
34
+ attribute :instrumentation
35
+
36
+ def initialize(args)
37
+ super(args)
38
+
39
+ @uri = URI.join(endpoint, path)
40
+ @uri.query = URI.encode_www_form(query)
41
+
42
+ @notification_payload = {
43
+ method: :get,
44
+ path: path,
45
+ query: query,
46
+ }
47
+ end
48
+
49
+ def execute
50
+ @started = Time.now.utc
51
+
52
+ req = Net::HTTP::Get.new(@uri)
53
+ req.basic_auth @api_key, ""
54
+
55
+ response = connection.request req
56
+ @notification_payload[:status] = response.code
57
+
58
+ begin
59
+ @notification_payload[:response] = parse(response, resource_type, resource_id)
60
+ rescue StandardError => e
61
+ @notification_payload[:error] = e
62
+ raise e
63
+ ensure
64
+ publish_notification
65
+ end
66
+ rescue Net::OpenTimeout, Net::ReadTimeout
67
+ raise TimeoutError
68
+ end
69
+
70
+ private
71
+
72
+ def publish_notification
73
+ instrumentation.publish(
74
+ "companies_house.#{resource_type}",
75
+ @started,
76
+ Time.now.utc,
77
+ transaction_id,
78
+ @notification_payload,
79
+ )
80
+ end
81
+
82
+ def parse(response, resource_type, resource_id)
83
+ case response.code
84
+ when "200"
85
+ JSON[response.body]
86
+ when "401"
87
+ raise CompaniesHouse::AuthenticationError, response
88
+ when "404"
89
+ raise CompaniesHouse::NotFoundError.new(resource_type, resource_id, response)
90
+ when "429"
91
+ raise CompaniesHouse::RateLimitError, response
92
+ when "502"
93
+ raise CompaniesHouse::BadGatewayError, response
94
+ else
95
+ raise CompaniesHouse::APIError.new("Unknown API response", response)
96
+ end
97
+ end
98
+ end
99
+ end
data/lib/companies_house/timeout_error.rb CHANGED
@@ -1,10 +1,10 @@
1
- # frozen_string_literal: true
2
-
3
- module CompaniesHouse
4
- # Raised when a request has timed out
5
- class TimeoutError < APIError
6
- def initialize(response = nil)
7
- super("Request timed out", response)
8
- end
9
- end
10
- end
1
+ # frozen_string_literal: true
2
+
3
+ module CompaniesHouse
4
+ # Raised when a request has timed out
5
+ class TimeoutError < APIError
6
+ def initialize(response = nil)
7
+ super("Request timed out", response)
8
+ end
9
+ end
10
+ end
data/lib/companies_house/version.rb CHANGED
@@ -1,5 +1,5 @@
1
- # frozen_string_literal: true
2
-
3
- module CompaniesHouse
4
- VERSION = "0.4.4"
5
- end
1
+ # frozen_string_literal: true
2
+
3
+ module CompaniesHouse
4
+ VERSION = "0.4.5"
5
+ end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: companies-house-rest
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.4
4
+ version: 0.4.5
5
5
  platform: ruby
6
6
  authors:
7
7
  - GoCardless Engineering
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2019-01-07 00:00:00.000000000 Z
11
+ date: 2019-08-29 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: activesupport
@@ -51,61 +51,61 @@ dependencies:
51
51
  - !ruby/object:Gem::Version
52
52
  version: 1.0.5
53
53
  - !ruby/object:Gem::Dependency
54
- name: bundler
54
+ name: gc_ruboconfig
55
55
  requirement: !ruby/object:Gem::Requirement
56
56
  requirements:
57
57
  - - "~>"
58
58
  - !ruby/object:Gem::Version
59
- version: '1.10'
59
+ version: '2.4'
60
60
  type: :development
61
61
  prerelease: false
62
62
  version_requirements: !ruby/object:Gem::Requirement
63
63
  requirements:
64
64
  - - "~>"
65
65
  - !ruby/object:Gem::Version
66
- version: '1.10'
66
+ version: '2.4'
67
67
  - !ruby/object:Gem::Dependency
68
- name: gc_ruboconfig
68
+ name: rake
69
69
  requirement: !ruby/object:Gem::Requirement
70
70
  requirements:
71
71
  - - "~>"
72
72
  - !ruby/object:Gem::Version
73
- version: '2.3'
73
+ version: '12.0'
74
74
  type: :development
75
75
  prerelease: false
76
76
  version_requirements: !ruby/object:Gem::Requirement
77
77
  requirements:
78
78
  - - "~>"
79
79
  - !ruby/object:Gem::Version
80
- version: '2.3'
80
+ version: '12.0'
81
81
  - !ruby/object:Gem::Dependency
82
- name: rake
82
+ name: rspec
83
83
  requirement: !ruby/object:Gem::Requirement
84
84
  requirements:
85
85
  - - "~>"
86
86
  - !ruby/object:Gem::Version
87
- version: '12.0'
87
+ version: '3.5'
88
88
  type: :development
89
89
  prerelease: false
90
90
  version_requirements: !ruby/object:Gem::Requirement
91
91
  requirements:
92
92
  - - "~>"
93
93
  - !ruby/object:Gem::Version
94
- version: '12.0'
94
+ version: '3.5'
95
95
  - !ruby/object:Gem::Dependency
96
- name: rspec
96
+ name: rspec_junit_formatter
97
97
  requirement: !ruby/object:Gem::Requirement
98
98
  requirements:
99
99
  - - "~>"
100
100
  - !ruby/object:Gem::Version
101
- version: '3.5'
101
+ version: 0.4.1
102
102
  type: :development
103
103
  prerelease: false
104
104
  version_requirements: !ruby/object:Gem::Requirement
105
105
  requirements:
106
106
  - - "~>"
107
107
  - !ruby/object:Gem::Version
108
- version: '3.5'
108
+ version: 0.4.1
109
109
  - !ruby/object:Gem::Dependency
110
110
  name: timecop
111
111
  requirement: !ruby/object:Gem::Requirement
@@ -150,6 +150,8 @@ files:
150
150
  - lib/companies_house/authentication_error.rb
151
151
  - lib/companies_house/bad_gateway_error.rb
152
152
  - lib/companies_house/client.rb
153
+ - lib/companies_house/instrumentation/active_support.rb
154
+ - lib/companies_house/instrumentation/null.rb
153
155
  - lib/companies_house/not_found_error.rb
154
156
  - lib/companies_house/rate_limit_error.rb
155
157
  - lib/companies_house/request.rb
@@ -167,15 +169,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
167
169
  requirements:
168
170
  - - ">="
169
171
  - !ruby/object:Gem::Version
170
- version: 2.5.1
172
+ version: 2.5.5
171
173
  required_rubygems_version: !ruby/object:Gem::Requirement
172
174
  requirements:
173
175
  - - ">="
174
176
  - !ruby/object:Gem::Version
175
177
  version: '0'
176
178
  requirements: []
177
- rubyforge_project:
178
- rubygems_version: 2.7.6
179
+ rubygems_version: 3.0.3
179
180
  signing_key:
180
181
  specification_version: 4
181
182
  summary: Look up UK company registration information