Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add company search restrictions parameter #89

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add company search restrictions parameter #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 32 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -162,7 +162,7 @@ Bug reports and pull requests are welcome on this project's

To get started:

``` shell
```shell
bundle install --path vendor
```

Expand Down
5 changes: 3 additions & 2 deletions lib/companies_house/client.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion spec/companies_house/client_spec.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,7 @@
query,
items_per_page: items_per_page,
start_index: start_index,
restrictions: restrictions,
)
end

Expand All @@ -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)
Expand Down