Merge pull request #33 from hmrc/TAV-347

[PS] TAV-347 - Add API platform documentation for search by postcode POST endpoint

public/api/conf/1.0/application.raml

@@ -24,7 +24,7 @@ uses:
 
 /misc/address-verification/lookup:
   get:
-    displayName: Lookup address
+    displayName: Lookup address (deprecated)
     description: |
       Lookup of postal and BFPO (British Forces Post Office) address details within the UK
     is: [headers.acceptHeader]
@@ -46,3 +46,19 @@ uses:
           application/json:
             type: !include docs/uk-address-object.json
             example: !include docs/example-response.json
+  post:
+    displayName: Lookup address
+    description: |
+      Lookup of postal and BFPO (British Forces Post Office) address details within the UK
+    is: [headers.acceptHeader]
+    securedBy: [ sec.x-application ]
+    body:
+      application/json:
+          type: !include docs/post-request.json
+          example: !include docs/example-post-request.json
+    responses:
+      200:
+        body:
+          application/json:
+            type: !include docs/uk-address-object.json
+            example: !include docs/example-response.json

public/api/conf/1.0/docs/example-post-request.json

@@ -0,0 +1,4 @@
+{
+  "postcode": "AA1 1ZZ",
+  "filter": "The Rectory"
+}

public/api/conf/1.0/docs/post-request.json

@@ -0,0 +1,32 @@
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/object1614266033.json",
+  "title": "Root",
+  "type": "object",
+  "required": [
+    "postcode"
+  ],
+  "properties": {
+    "postcode": {
+      "$id": "#root/postcode",
+      "title": "Postcode",
+      "description": "Full postcode to search for, all uppercase. The internal space may be omitted",
+      "type": "string",
+      "examples": [
+        "AA1 1ZZ",
+        "BB00 0BB"
+      ]
+    },
+    "filter": {
+      "$id": "#root/filter",
+      "title": "Filter",
+      "description": "Refine the search results further based on house number or street name",
+      "type": "string",
+      "examples": [
+        "The Rectory",
+        "1 High Street"
+      ]
+    }
+  }
+}