MTDSA-9541: Add RAML for create marriage allowance endpoint. (#62)

Create RAML documentation for 'Create Marriage Allowance' endpoint.

.bsp/sbt.json

@@ -0,0 +1 @@
+{"name":"sbt","version":"1.5.0","bspVersion":"2.0.0-M5","languages":["scala"],"argv":["/Users/lukejones/Library/Java/JavaVirtualMachines/adopt-openj9-1.8.0_292/Contents/Home/jre/bin/java","-Xms100m","-Xmx100m","-classpath","/Users/lukejones/Library/Application Support/JetBrains/IdeaIC2020.3/plugins/Scala/launcher/sbt-launch.jar","xsbt.boot.Boot","-bsp","--sbt-launch-jar=/Users/lukejones/Library/Application%20Support/JetBrains/IdeaIC2020.3/plugins/Scala/launcher/sbt-launch.jar"]}

.gitignore

@@ -21,5 +21,5 @@ node_modules/
 npm-debug.log
 yarn-debug.log
 yarn-error.log
-
+/.bsp
 

resources/public/api/conf/1.0/application.raml

@@ -29,20 +29,24 @@ uses:
   headers: headers.raml
 
 '/individuals':
-  uriParameters:
-    nino:
-      description: "National Insurance number, in the format AA999999A."
-      type: string
-      example: "TC663795B"
-    taxYear:
-      description: "The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)"
-      example: "2021-22"
   /disclosures:
-    (annotations.group):
-       name: Disclosures
-       description: Resources relating to an individual's disclosures
+    /marriage-allowance:
+        (annotations.group):
+          name: Marriage Allowance
+          description: Resources relating to an individual's marriage allowance.
+        /{nino}:
+          uriParameters:
+            nino: !include pathParameters/nino.raml
+          post: !include endpoints/marriageAllowance/create.raml
     /{nino}:
+      uriParameters:
+        nino: !include pathParameters/nino.raml
       /{taxYear}:
+        uriParameters:
+          taxYear: !include pathParameters/taxYear.raml
+        (annotations.group):
+          name: Disclosures
+          description: Resources relating to an individual's disclosures
         get: !include endpoints/disclosures/retrieve.raml
         delete: !include endpoints/disclosures/delete.raml
         put: !include endpoints/disclosures/amend.raml

resources/public/api/conf/1.0/endpoints/marriageAllowance/create.raml

@@ -0,0 +1,30 @@
+is:
+  - headers.acceptJson
+  - headers.contentTypeJson
+  - headers.testScenarioHeader
+  - errors.formatNino
+  - errors.formatSpouseOrCivilPartnersFirstName
+  - errors.formatSpouseOrCivilPartnersSurname
+  - errors.formatSpouseOrCivilPartnersNino
+  - errors.formatSpouseOrCivilPartnersDateOfBirth
+  - errors.ruleDeceasedRecipient
+  - errors.ruleActiveMarriageAllowanceClaim
+  - errors.clientOrAgentNotAuthorised
+  - errors.incorrectOrEmptyBody
+
+displayName: Create Marriage Allowance
+description: "This endpoint allows the customer to transfer up to £1,260 of their personal allowance to their spouse or civil partner. A National Insurance Number must be provided."
+(annotations.sandboxData): !include ../../scenarios/createMarriageAllowance.md
+(annotations.scope): "write:self-assessment"
+securedBy: [ sec.oauth_2_0: { scopes: [ "write:self-assessment" ] } ]
+body:
+   application/json:
+      type: !include ../../schemas/create_marriageAllowance_request.json
+      example:
+        value: !include ../../examples/marriageAllowance/create_marriageAllowance_request.json
+responses:
+  201:
+    headers:
+      X-CorrelationId:
+        example: c75f40a6-a3df-4429-a697-471eeec46435
+        description: Unique ID for operation tracking <br> String, 36 characters.

resources/public/api/conf/1.0/errors.raml

@@ -4,28 +4,6 @@ uses:
   types: https://developer.service.hmrc.gov.uk/api-documentation/assets/common/modules/types.raml
 
 traits:
-  notFound:
-    responses:
-      404:
-        body:
-          application/json:
-            type: types.errorResponse
-            examples:
-              notFound:
-                description: 'The supplied income source could not be found.'
-                value:
-                  code: MATCHING_RESOURCE_NOT_FOUND
-  clientOrAgentNotAuthorised:
-    responses:
-      403:
-        body:
-          application/json:
-            type: types.errorResponse
-            examples:
-              clientOrAgentNotAuthorised:
-                description: 'The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.'
-                value:
-                  code: CLIENT_OR_AGENT_NOT_AUTHORISED
   formatNino:
     responses:
       400:
@@ -92,6 +70,61 @@ traits:
                 description: 'The format of the supplied scheme reference number is not valid.'
                 value:
                   code: FORMAT_SRN_INVALID
+  voluntaryClass2Contributions:
+    responses:
+      400:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              voluntaryClass2Contributions:
+                description: 'Voluntary Class 2 Contributions can only be set to true.'
+                value:
+                  code: RULE_VOLUNTARY_CLASS2_VALUE_INVALID
+  formatSpouseOrCivilPartnersFirstName:
+    responses:
+      400:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              formatSpouseOrCivilPartnersFirstName:
+                description: "The format of your spouse or civil partner's first name is not valid."
+                value:
+                  code: FORMAT_SPOUSE_OR_CIVIL_PARTNERS_FIRST_NAME
+  formatSpouseOrCivilPartnersSurname:
+    responses:
+      400:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              formatSpouseOrCivilPartnersSurname:
+                description: "The format of your spouse or civil partner's surname name is not valid."
+                value:
+                  code: FORMAT_SPOUSE_OR_CIVIL_PARTNERS_SURNAME
+  formatSpouseOrCivilPartnersNino:
+    responses:
+      400:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              formatSpouseOrCivilPartnersNino:
+                description: "The format of your spouse or civil partner's National Insurance Number is not valid."
+                value:
+                  code: FORMAT_SPOUSE_OR_CIVIL_PARTNERS_NINO
+  formatSpouseOrCivilPartnersDateOfBirth:
+    responses:
+      400:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              formatSpouseOrCivilPartnersDateOfBirth:
+                description: "The format of the supplied spouse or civil partner's date of birth is not valid."
+                value:
+                  code: FORMAT_SPOUSE_OR_CIVIL_PARTNERS_DATE_OF_BIRTH
   voluntaryClass2CannotBeChanged:
     responses:
       403:
@@ -103,14 +136,47 @@ traits:
                 description: 'Voluntary Class 2 NICs cannot be changed after 31st Jan following the year of submission.'
                 value:
                   code: RULE_VOLUNTARY_CLASS2_CANNOT_BE_CHANGED
-  voluntaryClass2Contributions:
-      responses:
-        400:
-          body:
-            application/json:
-              type: types.errorResponse
-              examples:
-                voluntaryClass2Contributions:
-                  description: 'Voluntary Class 2 Contributions can only be set to true.'
-                  value:
-                    code: RULE_VOLUNTARY_CLASS2_VALUE_INVALID
+  ruleDeceasedRecipient:
+    responses:
+      403:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              ruleDeceasedRecipient:
+                description: "The supplied spouse or civil partner is invalid because they are deceased."
+                value:
+                  code: RULE_DECEASED_RECIPIENT
+  ruleActiveMarriageAllowanceClaim:
+    responses:
+      403:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              ruleActiveMarriageAllowanceClaim:
+                description: "The request cannot be made as there is an existing Marriage Allowance claim. "
+                value:
+                  code: RULE_ACTIVE_MARRIAGE_ALLOWANCE_CLAIM
+  clientOrAgentNotAuthorised:
+    responses:
+      403:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              clientOrAgentNotAuthorised:
+                description: 'The client or agent is not authorised. This is because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.'
+                value:
+                  code: CLIENT_OR_AGENT_NOT_AUTHORISED
+  notFound:
+    responses:
+      404:
+        body:
+          application/json:
+            type: types.errorResponse
+            examples:
+              notFound:
+                description: 'The supplied income source could not be found.'
+                value:
+                  code: MATCHING_RESOURCE_NOT_FOUND

resources/public/api/conf/1.0/examples/marriageAllowance/create_marriageAllowance_request.json

@@ -0,0 +1,6 @@
+{
+  "spouseOrCivilPartnerNino": "TC663795B",
+  "spouseOrCivilPartnerFirstName": "John",
+  "spouseOrCivilPartnerSurname": "Smith",
+  "spouseOrCivilPartnerDateOfBirth": "1987-10-18"
+}

resources/public/api/conf/1.0/pathParameters/nino.raml

@@ -0,0 +1,3 @@
+description: "National Insurance number, in the format AA999999A."
+type: string
+example: "TC663795B"

resources/public/api/conf/1.0/pathParameters/taxYear.raml

@@ -0,0 +1,3 @@
+description: "The tax year the data applies to, for example, 2021-22. The start year and end year must not span two tax years. The minimum tax year is 2021-22. No gaps are allowed, for example, 2020-22 is not valid. (The minimum tax year in Sandbox is 2019-20.)"
+type: string
+example: "2021-22"

resources/public/api/conf/1.0/scenarios/createMarriageAllowance.md

@@ -0,0 +1,23 @@
+<p>Scenario simulations using Gov-Test-Scenario headers is only available in the sandbox environment.</p>
+<table>
+    <thead>
+        <tr>
+            <th>Header Value (Gov-Test-Scenario)</th>
+            <th>Scenario</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td><p>N/A - DEFAULT</p></td>
+            <td><p>Simulates success response.</p></td>
+        </tr>   
+        <tr>
+            <td><p>DECEASED_RECIPIENT</p></td>
+            <td><p>Simulates the scenario in which the supplied spouse or civil partner has been flagged as deceased.</p></td>
+        </tr>
+        <tr>
+            <td><p>CLAIM_ALREADY_EXISTS</p></td>
+            <td><p>Simulates the scenario in which a Marriage Allowance claim already exists for the supplied NINO. </p></td>
+        </tr>
+    </tbody>
+</table>

resources/public/api/conf/1.0/schemas/create_marriageAllowance_request.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Create Marriage Allowance Request",
+  "description": "Create Marriage Allowance Request",
+  "type": "object",
+  "properties": {
+    "spouseOrCivilPartnerNino": {
+      "type": "string",
+      "description": "Your spouse or civil partner's National Insurance number.",
+      "format": "^((?!(BG|GB|KN|NK|NT|TN|ZZ)|(D|F|I|Q|U|V)[A-Z]|[A-Z](D|F|I|O|Q|U|V))[A-Z]{2})[0-9]{6}[A-D]$",
+      "example": "AA999999A"
+    },
+    "spouseOrCivilPartnerFirstName": {
+      "type": "string",
+      "description": "Your spouse or civil partner's first name.",
+      "minLength": 1,
+      "maxLength": 35,
+      "example": "John"
+    },
+    "spouseOrCivilPartnerSurname": {
+      "type": "string",
+      "description": "Your spouse or civil partner's surname.",
+      "minLength": 1,
+      "maxLength": 35,
+      "example": "Smith"
+    },
+    "spouseOrCivilPartnerDateOfBirth": {
+      "type": "string",
+      "description": "The date of birth of your spouse or civil partner in the format YYYY-MM-DD.",
+      "format": "[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "example": "1998-04-06"
+    }
+  },
+  "required": [
+    "spouseOrCivilPartnerSurname"
+  ]
+}