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
- Get started
- Reference
RegisterClientManager
RegisterClient
- Collections
- EntryCollection
- Entry
- ItemCollection
- Item
- RecordCollection
- Record
- RecordMapCollection
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_key
is the API key you received after signing-up your service on our product page. -
page_size
: number of results returned per page when using thepage
method of any of the collection classes (see below for more information) - default is100
Reference
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.
options = {
data_store: nil
}
registers_client.get_register('country', 'beta', options)
A RegisterClient instance e.g. #<RegistersClient::RegisterClient:0x00007f893c55f740>
Note: All examples use the Country register.
get_entries
Get all entries from the register.
register_data = registers_client.get_register('country', 'beta')
register_data.get_entries
An EntryCollection instance.
get_records
Get all records from the register.
register_data = registers_client.get_register('country', 'beta')
register_data.get_records
A RecordCollection instance.
get_metadata_records
Get all metadata records of the register. This includes the register definition, field definitions and custodian.
register_data = registers_client.get_register('country', 'beta')
register_data.get_metadata_records
A RecordCollection instance.
get_field_definitions
Get definitions for the fields used in the register.
register_data = registers_client.get_register('country', 'beta')
register_data.get_field_definitions
A RecordCollection instance.
get_register_definition
Get the definition of the register.
register_data = registers_client.get_register('country', 'beta')
register_data.get_register_definition
A Record instance.
get_custodian
Get the name of the current custodian for the register.
register_data = registers_client.get_register('country', 'beta')
register_data.get_custodian
A Record instance.
get_records_with_history
Get current and previous versions of records in the register.
register_data = registers_client.get_register('country', 'beta')
germany = register_data.get_records_with_history
A RecordMapCollection instance.
get_current_records
Get all current records from the register.
register_data = registers_client.get_register('country', 'beta')
register_data.get_current_records
A RecordCollection instance.
get_expired_records
Get all expired records from the register.
register_data = registers_client.get_register('country', 'beta')
register_data.get_expired_records
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.
register_data = registers_client.get_register('country', 'beta')
entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first
entry.entry_number
52
key
Gets the key of the entry.
register_data = registers_client.get_register('country', 'beta')
entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first
entry.key
CZ
timestamp
Gets the timestamp of when the entry was appended to the register.
register_data = registers_client.get_register('country', 'beta')
entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first
entry.timestamp
2016-04-05T13:23:05Z
item_hash
Gets the SHA-256 hash of the item which the entry points to.
register_data = registers_client.get_register('country', 'beta')
entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first
entry.item_hash
sha-256:c45bd0b4785680534e07c627a5eea0d2f065f0a4184a02ba2c1e643672c3f2ed
value
Returns the entry as a hash.
register_data = registers_client.get_register('country', 'beta')
entry = register_data.get_entries.select {|entry| entry.key == 'CZ'}.first
entry.value.to_json
"{"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.
register_data = registers_client.get_register('country', 'beta')
item = register_data.get_records.select {|record| record.entry.key == 'SU'}.first.item
item.hash
"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a"
value
Returns the key-value pairs represented by the item in a JSON
object.
register_data = registers_client.get_register('country', 'beta')
item = register_data.get_records.select {|record| record.entry.key == 'SU'}.first.item
item.value
{"item_json":"{\"citizen-names\":\"Soviet 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.
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
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.
register_data = registers_client.get_register('country', 'beta')
record = register_data.get_records.select {|record| record.entry.key == 'CZ'}.first
record.entry.to_json
"{"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.
register_data = registers_client.get_register('country', 'beta')
record = register_data.get_records.select {|record| record.entry.key == 'CZ'}.first
record.item.to_json
"{"item_json":"{\"citizen-names\":\"Czech\",\"country\":\"CZ\",\"name\":\"Czechia\",\"official-name\":\"The 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:
register_data = registers_client.get_register('country', 'beta')
register_data.get_records_with_history.each do |result|
puts result.to_json
end
"{"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":{"item_json":"{\"citizen-names\":\"Soviet 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.
register_data = registers_client.get_register('country', 'beta')
register_data.get_records_with_history.get_records_for_key('SU')
"{[{"entry":{"rsf_line":null,"entry_number":1,"parsed_entry":{"key":"SU","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a"}},"item":{"item_json":"{\"citizen-names\":\"Soviet 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
).
register_data = registers_client.get_register('country', 'beta')
enumerator = register_data.get_records_with_history.paginator
enumerator.next.to_json
[["SU",[{"entry":{"rsf_line":null,"entry_number":1,"parsed_entry":{"key":"SU","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:e94c4a9ab00d951dadde848ee2c9fe51628b22ff2e0a88bff4cca6e4e6086d7a"}},"item":{"item_json":"{\"citizen-names\":\"Soviet 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}}]],["DE",[{"entry":{"rsf_line":null,"entry_number":2,"parsed_entry":{"key":"DE","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:e03f97c2806206cdc2cc0f393d09b18a28c6f3e6218fc8c6f3aa2fdd7ef9d625"}},"item":{"item_json":"{\"citizen-names\":\"West German\",\"country\":\"DE\",\"end-date\":\"1990-10-02\",\"name\":\"West Germany\",\"official-name\":\"Federal Republic of Germany\"}","item_hash":"sha-256:e03f97c2806206cdc2cc0f393d09b18a28c6f3e6218fc8c6f3aa2fdd7ef9d625","parsed_item":null}},{"entry":{"rsf_line":null,"entry_number":71,"parsed_entry":{"key":"DE","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:747dbb718cb9f9799852e7bf698c499e6b83fb1a46ec06dbd6087f35c1e955cc"}},"item":{"item_json":"{\"citizen-names\":\"German\",\"country\":\"DE\",\"name\":\"Germany\",\"official-name\":\"The Federal Republic of Germany\",\"start-date\":\"1990-10-03\"}","item_hash":"sha-256:747dbb718cb9f9799852e7bf698c499e6b83fb1a46ec06dbd6087f35c1e955cc","parsed_item":n
ull}}]],
...
["AD",[{"entry":{"rsf_line":null,"entry_number":10,"parsed_entry":{"key":"AD","timestamp":"2016-04-05T13:23:05Z","item_hash":"sha-256:14fcb5099f0eff4c40d5a85b0e3c2f1a04337dc69dace1fc5c64ec9758a19b13"}},"item":{"item_json":"{\"citizen-names\":\"Andorran\",\"country\":\"AD\",\"name\":\"Andorra\",\"official-name\":\"The Principality of Andorra\"}","item_hash":"sha-256:14fcb5099f0eff4c40d5a85b0e3c2f1a04337dc69dace1fc5c64ec9758a19b13","parsed_item":null}}]]]"