This microservice provides a user interface for entering and editing addresses. Assistance is provided to the end-user for looking up their address from a database (via the backend service address-lookup).

Initially, the use-case covers only UK addresses. BFPO addresses might be added soon. The roadmap includes support for international addresses.

During the utilization of address-lookup-frontend, four parties are involved:

• A frontend service in the tax platform (the "calling service" here).
• The user-agent (i.e. web browser) and the user who operates it (the "user" here).
• The address-lookup-frontend (the "frontend" here).
• The backend address-lookup, containing large national datasets of addresses (the "backend" here).

The integration process from the perspective of the calling service consists of the following steps:

• Initialize a journey by issuing a request to POST /api/init where the message body is a journey configuration JSON message (see below). You should receive a 202 Accepted response with a Location header the value of which is the "on ramp" URL to which the "user" should be redirected.
• Redirect the "user" to the "on ramp" URL.
• The "user" completes the journey, following which they will be redirected to the "off ramp" URL (which is configured as part of the journey) with an appended id=:addressId URL parameter.
• Using the value of the id parameter, you can retrieve the user's confirmed address as JSON by issuing a request to GET /api/confirmed?id=:addressId.

The first action by any calling service must be to "initialize" an address lookup journey in order to obtain an "on ramp" URL to which the "user" is then redirected.

Initialization generates an ID which is utilized both to facilitate subsequent retrieval of the "user's" confirmed address and to prevent arbitrary access to and potential abuse of address-lookup-frontend by malicious "users".

An endpoint is provided for initialization:

URL:

• /api/init

Methods:

• POST

Headers:

• User-Agent (required): string

Message Body:

• A journey configuration message in application/json format (see details of the JSON format below)

Status Codes:

• 202 Accepted: when initialization was successful
• 500 Internal Server Error: when, for any (hopefully transient) internal reason, the journey could not be initialized

Response:

• No content
• The Location header will specify an "on ramp" URL, appropriate for the journey, to which the user should be redirected. Currently, the journey has a TTL of 60 minutes.

The address-lookup-frontend allows the "calling service" to customize many aspects of the "user's" journey and the appearance of the "frontend" user interface. Journey configuration is supplied as a JSON object in the body of the request to POST /api/init (see above).

It is not necessary to specify values for all configurable properties. Only supply a value for properties where it is either required or you need to override the default. Wherever possible, sensible defaults have been provided. The default values are indicated in the table detailing the options below.

Journey configuration is supplied as a JSON object in the body of the request to POST /api/init.

It is not necessary to specify values for all configurable properties. Only supply a value for properties where it is either required or you need to override the default. Wherever possible, sensible defaults have been provided. The default values are indicated in the table detailing the options below.

{
  "continueUrl" : "/lookup-address/confirmed",
  "homeNavHref" : "http://www.hmrc.gov.uk/",
  "navTitle" : "Address Lookup",
  "showPhaseBanner" : false,
  "alphaPhase" : false,
  "phaseFeedbackLink" : "/help/alpha",
  "phaseBannerHtml" : "This is a new service – your <a href='/help/alpha'>feedback</a> will help us to improve it.",
  "showBackButtons": false,
  "includeHMRCBranding" : true,
  "deskProServiceName" : "",
  "lookupPage" : {
    "title" : "Lookup Address",
    "heading" : "Your Address",
    "filterLabel" : "Building name or number",
    "postcodeLabel" : "Postcode",
    "submitLabel" : "Find my address",
    "noResultsFoundMessage" : "Sorry, we couldn't find anything for that postcode.",
    "resultLimitExceededMessage" : "There were too many results. Please add additional details to limit the number of results.",
    "manualAddressLinkText" : "Enter address manually"
  },
  "selectPage" : {
    "title" : "Select Address",
    "heading" : "Select Address",
    "proposalListLabel" : "Please select one of the following addresses",
    "submitLabel" : "Next",
    "proposalListLimit" : 50,
    "showSearchAgainLink" : false,
    "searchAgainLinkText" : "Search again",
    "editAddressLinkText" : "Edit address"
  },
  "confirmPage" : {
    "title" : "Confirm Address",
    "heading" : "Confirm Address",
    "infoSubheading" : "Your selected address",
    "infoMessage" : "This is how your address will look. Please double-check it and, if accurate, click on the <kbd>Confirm</kbd> button.",
    "submitLabel" : "Confirm",
    "showSearchAgainLink" : false,
    "searchAgainLinkText" : "Search again",
    "changeLinkText" : "Edit this address"
  },
  "editPage" : {
    "title" : "Edit Address",
    "heading" : "Edit Address",
    "line1Label" : "Line 1",
    "line2Label" : "Line 2",
    "line3Label" : "Line 3",
    "townLabel" : "Town",
    "postcodeLabel" : "Postcode",
    "countryLabel" : "Country",
    "submitLabel" : "Next",
    "showSearchAgainLink" : false,
    "searchAgainLinkText" : "Search again"
  }
}

Configuration of the "lookup" page, in which user searches for address using filter + postcode. The lookup page configuration is a nested JSON object inside the journey configuration under the lookupPage property.

Configuration of the "select" page, in which user chooses an address from a list of search results. The select page configuration is a nested JSON object inside the journey configuration under the selectPage property.

Configuration of the "confirm" page, in which the user is requested to confirm a "finalized" form for their address. The confirm page configuration is a nested JSON object inside the journey configuration under the confirmPage property.

Configuration of the "edit" page, in which the user is permitted to manually enter or modify a selected address. The confirm page configuration is a nested JSON object inside the journey configuration under the editPage property.

Additional configuration options may be introduced in future; for instance to prohibit "edit", to bypass "lookup", or to modify validation procedures for international or BFPO addresses. However, the design intent is that all configuration options should always have a default value. Consequently, "calling services" should only ever need to provide overrides to specific keys, rather than re-configuring or duplicating the entire journey for each scenario.

Once the user has completed the address lookup journey, they will be redirected to the off ramp URL specified in the journey configuration. An id parameter will be appended to the off ramp URL. Calling services may use the value of this parameter to obtain the user's confirmed address.

URL:

• /api/confirmed

Example URLs:

• /api/confirmed?id=ID_VALUE_FROM_APPENDED_OFF_RAMP_URL_ID_PARAMETER_HERE

Methods:

• GET

Headers:

• User-Agent (required): string

Message Body:

• None

Status Codes:

• 200 Ok: when a confirmed address was successfully obtained for the given ID
• 404 Not Found: when no confirmed address was found for the given ID
• 500 Internal Server Error: when, for any (hopefully transient) internal reason, the journey data corresponding to the ID could not be obtained

Response:

• An application/json message which describes a confirmed address (see below)

TODO

TODO

This code is open source software licensed under the Apache 2.0 License