|
Note
|
This documentation is limited by GitHub’s version of ASCII Docs, the full version may be viewed in the docs repo: https://ukhomeoffice.github.io/lev-api-docs |
|
Important
|
The contents of this repo are automatically generated; to make changes follow these steps:
|
It is possible to run a mock version of the API as follows:
The latest version of the mock API can be run straight from the quay.io hosted image:
docker pull quay.io/ukhomeofficedigital/lev-api-mock
docker run -p 8080:8080 quay.io/ukhomeofficedigital/lev-api-mock|
Note
|
The paths in this section refer to the root of the docs project: https://github.com/UKHomeOffice/lev-api-docs |
The easiest way to run the mock API is with Docker
./mock/build_mock_api_docker.sh
./mock/run_mock_api_docker.shTo use the API you will need to provide 2 forms of authentication:
-
A client certificate
-
An auth token, which must be obtained by hitting the
/oauth/loginendpoint
|
Important
|
The client certificate must be included in every request to the API, but is NOT shown in this documentation for simplicity. Adding a client certificate to a curl --cert-type pem --key client.key --cert client.crt ... |
|
Note
|
The client certificate is not needed when sending requests to the mock API. |
The rest of this section contains examples which have been provided to help troubleshoot issues with authentication.
Example curl request with dummy credentials
Example HTTP request with dummy credentials
Example response containing the access token
Generally authentication problems are reported as 401 Unauthorized errors.
Example curl request with invalid credentials
Example HTTP request with invalid credentials
Example response detailing the error
Example curl request without the required Authorization header
Example HTTP request without the required Authorization header
Example response detailing the error
Example curl request without the required password parameter
Example HTTP request without the required password parameter
Example response detailing the error
Whilst none of the examples here contain the required client certificate, this example
has been explicitly included to show how the resulting 403 Forbidden error would
look.
Example curl request without the required client certificate
Example HTTP request without the required client certificate
Example response detailing the error
All successful requests to the API will result in a 200 OK HTTP status code and are
described in this section.
The best way to get birth data is by providing the relevant System Number, a nine digit unique identifier for the birth record.
Example curl request specifying a System Number
Example HTTP request specifying a System Number
Example response is a JSON object containing the birth record data
When the System Number of the birth record is not known, a search of the records can be made by supplying the following three parameters in the URL query string:
-
forenames: the first name is mandatory, and can be accompanied by any middle names (all separated by spaces) -
lastname: the last name is mandatory -
dateofbirth: the date of birth is also mandatory
Example curl request with search parameters
Example HTTP request with search parameters
Example response is a JSON array containing three matching birth records
|
Tip
|
The API will only return at most 25 matching records. In the unlikely case where there might be more than 25 people with the same first name, last name, and date of birth; you will have to add middle names to the query to make the search more exacting. |
If no records matching the search terms can be found, the API will return an empty array.
Example curl request
Example HTTP request
Example response is an empty JSON array
Making a request to an invalid end point will result in the standard 404 Not Found
error.
Example curl request to an invalid endpoint
Example HTTP request to an invalid endpoint
Example response detailing the error
Example curl request with a non-existing System Number
Example HTTP request with a non-existing System Number
Example response detailing the error
Missing search parameters will result in a standard 400 Bad Request error.
Example curl request without the forenames parameter
Example HTTP request without the forenames parameter
Example response detailing the error
Example curl request without the lastname parameter
Example HTTP request without the lastname parameter
Example response detailing the error
Example curl request without the required dateofbirth parameter
Example HTTP request without the required dateofbirth parameter
Example response detailing the error
Example curl request with an incorrect dateofbirth parameter
Example HTTP request with an incorrect dateofbirth parameter
Example response detailing the error
|
Note
|
Currently the response status is 500 Internal Server Error; this is not the
intention and will be fixed in a future release to show the proper 400 Bad Request
instead.
|
The easiest way to provide forenames is using the forenames parameter, however
forenames may alternatively be provided using the numbered version: forename1,
forename2, forename3, and forenames4. Providing a mix of the forename parameters
will result in a standard 400 Bad Request error.
Example curl request with both forenames and forename1 parameters
Example HTTP request with both forenames and forename1 parameters
Example response detailing the error
|
Note
|
The use of forename1, forename2, forename3, and forename4 is strongly
discouraged and should be considered deprecated in favour of the forenames parameter.
|
For certain users with special permissions, it is possible to retrieve an aggregated count of system users' search activity.
All requests to the audit information end points must be made by a user with auditor
level permissions, otherwise the request will fail with the standard 401
Unauthorised error.
Example curl request by an API user without the special auditor permissions
Example HTTP request by an API user without the special auditor permissions
Example response detailing the error
The audit record data returned can be filtered by providing the following parameters.
The date range is optional. It can be omitted entirely, only one part specified, or
fully specified by providing the from and to date parameters.
Example curl request filtering out records except those made between yesterday
and one minute ago
Example HTTP request filtering out records except those made between yesterday
and one minute ago