GOV.UK Registers Ruby Client
You can use this Ruby client to integrate your service with GOV.UK Registers.
Registers are authoritative lists of information. The data is owned by custodians inside departments and services. For example, the Country register is maintained by a custodian in the Foreign and Commonwealth Office (FCO).
Table of Contents
Installation
In your Gemfile, add:
gem 'govuk-registers-api-client'
Get started
The RegisterClientManager is the entry point of the Registers Ruby client:
require 'register_client_manager'
registers_client = RegistersClient::RegisterClientManager.new({
api_key: "YOUR API KEY HERE",
page_size: 10
})
The RegisterClientManager maintains individual instances of RegisterClient for each register you access via the get_register method.
When creating a new RegisterClientManager, you can pass a configuration object to specify the following:
- The
api_keyis the API key you received after signing-up your service on our product page. page_size: number of results returned per page when using thepagemethod of any of the collection classes (see below for more information) - default is100
Reference
RegisterClientManager
get_register(register, phase, options = {})
Gets the RegisterClient instance for the given register name and phase.
You can pass an optional options object, which can include the following properties:
- data_store
The data_store specifies the data store to use accessing a particular register. You can omit this parameter, which will make it default to the InMemoryDataStore value. You can also create a custom data store to include the DataStore module and to implement the methods it defines. For example, to insert register data directly into your Postgres database.
Example use (click here to expand):
``` options = { data_store: nil } registers_client.get_register('country', 'beta', options) ```Expected output (click here to expand):
``` A RegisterClient instance e.g. #RegisterClient
Note: All examples use the Country register.
get_entries
Get all entries from the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_entries ```Expected output (click here to expand):
``` An EntryCollection instance. ```get_records
Get all records from the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_records ```Expected output (click here to expand):
``` A RecordCollection instance. ```get_metadata_records
Get all metadata records of the register. This includes the register definition, field definitions and custodian.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_metadata_records ```Expected output (click here to expand):
``` A RecordCollection instance. ```get_field_definitions
Get definitions for the fields used in the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_field_definitions ```Expected output (click here to expand):
``` A RecordCollection instance. ```get_register_definition
Get the definition of the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_register_definition ```Expected output (click here to expand):
``` A Record instance. ```get_custodian
Get the name of the current custodian for the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_custodian ```Expected output (click here to expand):
``` A Record instance. ```get_records_with_history
Get current and previous versions of records in the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') germany = register_data.get_records_with_history ```Expected output (click here to expand):
``` A RecordMapCollection instance. ```get_current_records
Get all current records from the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_current_records ```Expected output (click here to expand):
``` A RecordCollection instance. ```get_expired_records
Get all expired records from the register.
Example use (click here to expand)
``` register_data = registers_client.get_register('country', 'beta') register_data.get_expired_records ```Expected output (click here to expand)
``` A RecordCollection instance. ```refresh_data
Downloads register data. Call this method when you want to refresh data.
Collections
The majority of the methods available in the RegisterClient return one of three types of collection object. These collections all include Enumerable and implement the each method.
EntryCollection,
ItemCollection and RecordCollection are all Enumerable and implement the same Collections interface.
EntryCollection
A collection of Entry objects.
each
Yields each Entry object in the collection.
page(int page=1)
Returns all Entry objects in the collection, according to the specified page number (defaults to 1).
If there are fewer results than the current page_size, all results are returned.
Entry
entry_number
Gets the entry number of the entry.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first entry.entry_number ```Expected output (click here to expand):
``` 52 ```key
Gets the key of the entry.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first entry.key ```Expected output (click here to expand):
``` CZ ```timestamp
Gets the timestamp of when the entry was appended to the register.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first entry.timestamp ```Expected output (click here to expand):
``` 2016-04-05T13:23:05Z ```item_hash
Gets the SHA-256 hash of the item which the entry points to.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first entry.item_hash ```Expected output (click here to expand):
``` sha-256:c45bd0b4785680534e07c627a5eea0d2f065f0a4184a02ba2c1e643672c3f2ed ```value
Returns the entry as a hash.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first entry.value.to_json ```Expected output (click here to expand):
``` ""key":"CZ","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:c45bd0b4785680534e07c627a5eea0d2f065f0a4184a02ba2c1e643672c3f2ed"" ```ItemCollection
A collection of Item objects.
each
Yields each Item object in the collection.
page(int page=1)
Returns all Item objects in the collection, according to the specified page number (defaults to 1).
If there are fewer results than the current page_size, all results are returned.
Item
hash
Returns the SHA-256 hash of the item.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') item = register_data.get_records.select {|record| record.entry.key == 'SU'}.first.item item.hash ```Expected output (click here to expand):
``` "sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a" ```value
Returns the key-value pairs represented by the item in a JSON object.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') item = register_data.get_records.select {|record| record.entry.key == 'SU'}.first.item item.value ```Expected output (click here to expand):
``` citizen\",\"country\":\"SU\",\"end-date\":\"1991-12-25\",\"name\":\"USSR\",\"official-name\":\"Union of Soviet Socialist Republics\"","item_hash":"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a","parsed_item":null} ```has_end_date
Returns a boolean to describe whether the item contains a key-value pair for the end-date field.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') item = register_data.get_records.select {|record| record.entry.key == 'SU'}.first.item item.has_end_date ```Expected output (click here to expand):
``` true ```RecordCollection
A collection of Record objects.
each
Yields each Record object in the collection.
page(int page=1)
Returns Record objects in the collection, according to the specified page number (defaults to 1).
If there are fewer results than the current page_size, all results are returned.
Record
entry
Gets the Entry object associated with the record.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') record = register_data.get_records.select {|record| record.entry.key == 'CZ'}.first record.entry.to_json ```Expected output (click here to expand):
``` ""entry_number":205,"parsed_entry":{"key":"CZ","timestamp":"2016-11-11T16:25:07Z","item_hash":"sha-256:c69c04fff98c59aabd739d43018e87a25fd51a00c37d100721cc68fa9003a720"}" ```item
Gets the Item object associated with the record.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') record = register_data.get_records.select {|record| record.entry.key == 'CZ'}.first record.item.to_json ```Expected output (click here to expand):
``` "Czech Republic\",\"start-date\":\"1993-01-01\"","item_hash":"sha-256:c69c04fff98c59aabd739d43018e87a25fd51a00c37d100721cc68fa9003a720","parsed_item":null}" ```RecordMapCollection
A map of record key to list of both the current and historical Record objects for each key.
each
Yields each record key to list of current and historical Record objects in the collection, in the following format:
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_records_with_history.each do |result| puts result.to_json end ```Expected output for the first `result` (click here to expand):
``` ""key":"SU","records":[{"entry":{"rsf_line":null,"entry_number":1,"parsed_entry":{"key":"SU","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a"},"item":citizen\",\"country\":\"SU\",\"end-date\":\"1991-12-25\",\"name\":\"USSR\",\"official-name\":\"Union of Soviet Socialist Republics\"","item_hash":"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a","parsed_item":null}}]}" ```get_records_for_key(string key)
Returns both the current and historical Record objects for a given key, or raises a KeyError if no records exist for the given key.
Example use (click here to expand):
``` register_data = registers_client.get_register('country', 'beta') register_data.get_records_with_history.get_records_for_key('SU') ```Expected output (click here to expand):
``` "[{"entry":{"rsf_line":null,"entry_number":1,"parsed_entry":{"key":"SU","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a"},"item":citizen\",\"country\":\"SU\",\"end-date\":\"1991-12-25\",\"name\":\"USSR\",\"official-name\":\"Union of Soviet Socialist Republics\"","item_hash":"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a","parsed_item":null}}]}" ```paginator
Returns an enumerator of a map of record key to list of current and historical Record objects in the collection, in slices specified by page_size (defined when creating the RegisterClientManager).