[PS] Update POST urls to reflect the current format, removed outcode …

…search and re-ordered endpoints by significance
hmrc · Sep 28, 2021 · 1af0a33 · 1af0a33
1 parent c7e5646
commit 1af0a33
Showing 1 changed file with 26 additions and 111 deletions.
diff --git a/public/api/conf/1.0/docs/address-lookup-api.md b/public/api/conf/1.0/docs/address-lookup-api.md
@@ -49,82 +49,17 @@ addresses is returned. The response format is a _JSON array_ containing *zero or
 
 If an address is a PO Box the response will contain an optional attribute named `poBox`, see the [PO Box example response](example-response-pobox.json).
 
-### 3A. (POST) Lookup by UPRN
-
-This is an endpoint that searches for the address(es) of a given UPRN.
-
-URL:
-
- - `{contextPath}/v2/uk/addresses`
- - `{contextPath}/v2/gb/addresses` (alias for `uk`)
-
-Example URL:
-
- - `{contextPath}/v2/uk/addresses`
-   ```json
-      {
-        "uprn": "1234512345"
-      }
-   ```
-
-Methods:
-
- - `POST`
-
-Headers:
-
- - `User-Agent` (required): *string*
-
-   This identifies the origin of the request so that usage patterns can be tracked. The value will be a short
-   string containing some code-name of the originating service, e.g. `yta`. It must not contain '/' to avoid
-   problems with default User-Agent values.
-   It will be used for reporting. All requests from a given origin must carry the same code-name.
-
- - `X-Hmrc-Origin` (alternative): *string*
-
-   The is an alternative to `User-agent`; only one of these is required.
-
- - `Accept-Language` (optional): two-letter ISO639-1 case-insensitive code list
-
-   Example:
-
-     - `Accept-Language: cy, en`
-
-   If no match was made, the default response will be sent, which will typically be English.
-
-   Note that clients of this service that have user-facing UIs may pass the Accept-Language
-   header sent by the user-agent through directly.
-
-Body:
-```json
-{
-   "uprn": "1234512345"
-}
-```
-Status codes:
-
- - *200-OK* when the postcode search was successful (n.b. response might be `[]`)
- - others as in section 1.
-
-Response:
-
- - `Content-Type: application/json`
- - Expiry and cache control headers will be set appropriately.
- - The body will be a _JSON array_ containing *zero or more* [UK Address Objects (v2)](uk-address-object.json).
-     [Example response (v2)](example-response-multiple.json)
-
-### 3B. (POST) Lookup by Postcode
+### 3A. (POST) Lookup by Postcode
 
 This is an endpoint that searches for addresses at a given postcode.
 
 URL:
 
- - `{contextPath}/v2/uk/addresses`
- - `{contextPath}/v2/gb/addresses` (alias for `uk`)
+ - `{contextPath}/lookup
 
 Example URL:
 
- - `{contextPath}/v2/uk/addresses`
+ - `{contextPath}/lookup`
    ```json
    {
       "postcode": "AA1 1ZZ",
@@ -183,21 +118,20 @@ Response:
  - The body will be a _JSON array_ containing *zero or more* [UK Address Objects (v2)](uk-address-object.json).
      [Example response (v2)](example-response-multiple.json)
 
-### 3C. (POST) Lookup by Outcode
+### 3B. (POST) Lookup by Town
 
-This is an endpoint that searches for addresses within a given outcode (the first half of a postcode).
+This is an endpoint that searches for addresses within a given postal town
 
 URL:
 
- - `{contextPath}/v2/uk/addresses`
- - `{contextPath}/v2/gb/addresses` (alias for `uk`)
+ - `{contextPath}/lookup/by-post-town
 
 Example URL:
 
- - `{contextPath}/v2/uk/addresses`
+ - `{contextPath}/lookup/by-post-town
    ```json
    {
-      "outcode": "AA1",
+      "posttown": "Test town",
       "filter": "The Rectory"
    }
    ```
@@ -233,16 +167,16 @@ Headers:
 Body:
    ```json
    {
-      "outcode": "AA1",
+      "posttown": "Test town",
       "filter": "The Rectory"
    }
    ```
- - `outcode` (required) the first half of a postcode, all uppercase.
- - `filter` (required): a sub-string match on any of the address lines.
+ - `posttown` (required): the postal town of the address.
+ - `filter` (optional): a sub-string match on any of the address lines.
 
 Status codes:
 
- - *200-OK* when the outcode search was successful (n.b. response might be `[]`)
+ - *200-OK* when the search was successful (n.b. response might be `[]`)
  - others as in section 1.
 
 Response:
@@ -251,27 +185,22 @@ Response:
  - Expiry and cache control headers will be set appropriately.
  - The body will be a _JSON array_ containing *zero or more* [UK Address Objects (v2)](uk-address-object.json).
      [Example response (v2)](example-response-multiple.json)
+
+### 3C. (POST) Lookup by UPRN
 
-### 3D. (POST) Arbitrary Address Match
-
-This is a more advanced query endpoint that takes an arbitrary address and searches for the best match or matches.
-The canonical address(es) is returned.
+This is an endpoint that searches for the address(es) of a given UPRN.
 
 URL:
 
- - `{contextPath}/v2/uk/addresses`
- - `{contextPath}/v2/gb/addresses` (alias for `uk`)
+ - `{contextPath}/lookup/by-uprn`
 
 Example URL:
 
- - `{contextPath}/v2/uk/addresses
+ - `{contextPath}/lookup/by-uprn`
    ```json
-   {
-      "postcode": "AA1 1ZZ",
-      "line1": "The Rectory",
-      "line2": "Church Street",
-      "town": "Townham"
-   }
+      {
+        "uprn": "1234512345"
+      }
    ```
 
 Methods:
@@ -303,26 +232,14 @@ Headers:
    header sent by the user-agent through directly.
 
 Body:
-
-   ```json
-   {
-      "postcode": "AA1 1ZZ",
-      "line1": "The Rectory",
-      "line2": "Church Street",
-      "town": "Townham"
-   }
-   ```
- - `line1` (optional): the first line of the input address
- - `line2` (optional): the second line of the input address
- - `line3` (optional): the third line of the input address
- - `line4` (optional): the fourth line of the input address
- - `town` (optional): the name of the town in the input address, if not included in lines 1-4
- - `postcode` (optional) in the usual Royal Mail format, all uppercase. The internal space may be omitted.
- - `limit` (optional) a positive integer that constrains the number of matching addresses found (this reduces server load considerably).
-
+```json
+{
+   "uprn": "1234512345"
+}
+```
 Status codes:
 
- - *200-OK* when the search was successful (n.b. response might be `[]`)
+ - *200-OK* when the postcode search was successful (n.b. response might be `[]`)
  - others as in section 1.
 
 Response:
@@ -333,8 +250,6 @@ Response:
      [Example response (v2)](example-response-multiple.json)
 
 
-
-
 ## 4. Liveness Test
 
 URL: