From c02a528e0792f4fbc74d480ac8dfeb3a3771a384 Mon Sep 17 00:00:00 2001 From: Tomislav Simnett Date: Mon, 9 Dec 2024 15:39:23 +0000 Subject: [PATCH] Add company search restrictions parameter --- README.md | 64 ++++++++++++++--------------- lib/companies_house/client.rb | 5 ++- spec/companies_house/client_spec.rb | 5 ++- 3 files changed, 39 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 6cf0916..6039045 100644 --- a/README.md +++ b/README.md @@ -14,19 +14,19 @@ see the gem [companies-house-gateway](https://github.com/gocardless/companies-ho 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): +- 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 +```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: +- Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest) +- Create and use a client: -``` ruby +```ruby require 'companies_house/client' client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY']) profile = client.company('07495895') @@ -52,11 +52,11 @@ Developers should read 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 +- 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 @@ -70,11 +70,11 @@ 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. | +| 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) | -| `:instrumentation` | Optional. Instruments the request/response (see Instrumentation for details) | +| `:instrumentation` | Optional. Instruments the request/response (see Instrumentation for details) | ## Instrumentation @@ -88,11 +88,11 @@ 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_search(query, items_per_page: nil, start_index: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. | +| 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_search(query, items_per_page: nil, start_index: nil, restrictions: nil)` | `GET /search/companies` | Retrieves a list of companies that match the given query. | ### .company @@ -113,7 +113,7 @@ resource(s) which it reads. This method implements the [searchCompanies](https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html) API and returns the list of [companySearch](https://developer.companieshouse.gov.uk/api/docs/search-overview/CompanySearch-resource.html) -resources that match the given query. The `items_per_page` and `start_index` parameters are optional. +resources that match the given query. The `items_per_page`, `start_index` and `restrictions` parameters are optional. ### .filing_history_list @@ -136,22 +136,22 @@ 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 | -| ---------- | ----------- | +| Field | Description | +| ---------- | ------------------------------------------------------- | | `response` | The Net::HTTP response object from the failed API call. | -| `status` | A string containing the response status code. | +| `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.) | +| 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`). +errors involving network connections (e.g. `Errno::ECONNRESET`). ## Development @@ -162,7 +162,7 @@ Bug reports and pull requests are welcome on this project's To get started: -``` shell +```shell bundle install --path vendor ``` diff --git a/lib/companies_house/client.rb b/lib/companies_house/client.rb index 708a2a5..3893dca 100644 --- a/lib/companies_house/client.rb +++ b/lib/companies_house/client.rb @@ -80,12 +80,13 @@ def filing_history_item(id, transaction_id) ) end - def company_search(query, items_per_page: nil, start_index: nil) + def company_search(query, items_per_page: nil, start_index: nil, restrictions: nil) request( resource: :company_search, path: "search/companies", params: { - q: query, items_per_page: items_per_page, start_index: start_index + q: query, items_per_page: items_per_page, start_index: start_index, + restrictions: restrictions }.compact, ) end diff --git a/spec/companies_house/client_spec.rb b/spec/companies_house/client_spec.rb index 9c2b65d..4b262b0 100644 --- a/spec/companies_house/client_spec.rb +++ b/spec/companies_house/client_spec.rb @@ -410,6 +410,7 @@ query, items_per_page: items_per_page, start_index: start_index, + restrictions: restrictions, ) end @@ -418,16 +419,18 @@ q: query, items_per_page: items_per_page, start_index: start_index, + restrictions: restrictions, } end let(:items_per_page) { 5 } let(:start_index) { 3 } + let(:restrictions) { "active-companies" } before do stub_request( :get, "#{example_endpoint}/#{rest_path}?items_per_page=#{items_per_page}\ -&q=#{query}&start_index=#{start_index}", +&q=#{query}&start_index=#{start_index}&restrictions=#{restrictions}", ). with(basic_auth: [api_key, ""]). to_return(body: '{"companies": "data"}', status: status)