Skip to content
This repository has been archived by the owner on Mar 15, 2021. It is now read-only.

Latest commit

 

History

History
813 lines (529 loc) · 17.7 KB

README.md

File metadata and controls

813 lines (529 loc) · 17.7 KB
Raw

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_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 the page method of any of the collection classes (see below for more information) - default is 100

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. #<RegistersClient::RegisterClient:0x00007f893c55f740>

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): 

{"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.

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): 
"{"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:

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":{"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.

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":{"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).

Example use (click here to expand): 

register_data = registers_client.get_register('country', 'beta')

enumerator = register_data.get_records_with_history.paginator
enumerator.next.to_json
Expected output (click here to expand): 

[["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}}]]]"