Schema updated

hmrc · Nov 23, 2017 · 6ae6a7f · 6ae6a7f
1 parent 9b8dee8
commit 6ae6a7f
Show file tree

Hide file tree

Showing 8 changed files with 143 additions and 114 deletions.
diff --git a/resources/public/api/conf/1.0/application.raml b/resources/public/api/conf/1.0/application.raml
@@ -35,7 +35,7 @@ types:
   TaxOfficeReference:
     pattern: "[a-zA-Z0-9]{7}"
 
-/paye-for-employers:
+/organisation/paye:
   /:
     get:
       is: [ headers.acceptHeader ]
@@ -61,7 +61,7 @@ types:
                       "code" : "INSUFFICIENT_ENROLMENTS",
                       "message" : "You are not currently enrolled for ePAYE"
                     }
-  /{taxOfficeNumber}/{taxOfficeReference}/total:
+  /{taxOfficeNumber}/{taxOfficeReference}/:
     uriParameters:
       taxOfficeNumber:
         description: A unique identifier made up of tax office number
@@ -74,15 +74,15 @@ types:
     get:
       is: [ headers.acceptHeader ]
       displayName: Get ePAYE total balance
-      description: This resource returns the total balance including interest on your ePAYE account.
+      description: This resource returns the account summary including outstanding balance and interest on your ePAYE account.
       (annotations.scope): "read:epaye"
       securedBy: [ sec.oauth_2_0: { scopes: [ "read:epaye" ] } ]
       responses:
         200:
           body:
             application/json:
-              type: !include schemas/Totals.get.schema.json
-              example: !include examples/Totals.get.json
+              type: !include schemas/Summary.get.schema.json
+              example: !include examples/Summary.get.json
         403:
           body:
             application/json:
@@ -95,73 +95,4 @@ types:
                       "code" : "INVALID_EMPREF",
                       "message" : "Provided EmpRef is not associated with your account"
                     }
-    /by-type:
-      get:
-        is: [ headers.acceptHeader ]
-        displayName: Get ePAYE balance by type
-        description: This resource returns the total balance including interest on your ePAYE account for RTI and Non-RTI charges.
-        (annotations.scope): "read:epaye"
-        securedBy: [ sec.oauth_2_0: { scopes: [ "read:epaye" ] } ]
-        responses:
-          200:
-            body:
-              application/json:
-                type: !include schemas/Totals.ByType.get.schema.json
-                example: !include examples/Totals.ByType.get.json
-          403:
-            body:
-              application/json:
-                type: !include schemas/ErrorCodes.schema.json
-                examples:
-                  notOpenStatus:
-                    description: You don't currently have an ePAYE enrolment on this account.
-                    value: |
-                      {
-                        "code" : "INSUFFICIENT_ENROLMENTS",
-                        "message" : "You are not currently enrolled for ePAYE"
-                      }
-  /{taxOfficeNumber}/{taxOfficeReference}/charges-summary/?taxYear={taxYear}:
-    uriParameters:
-      taxOfficeNumber:
-        description: A unique identifier made up of tax office number
-        type: string
-        example: "001"
-      taxOfficeReference:
-        description: A unique identifier made up of the tax office reference
-        type: string
-        example: "A000001"
-      taxYear:
-        description: string identifying a tax year, if not given, current tax year assumed
-        type: string
-        example: "2016-17"
-    get:
-      is: [ headers.acceptHeader ]
-      displayName: Get RTI and non-RTI charges summary
-      description: This resource returns open RTI charges grouped by tax month and non-RTI charges grouped by type, for the given tax year or current tax year if tax year query parameter is missing
-      (annotations.scope): "read:epaye"
-      securedBy: [ sec.oauth_2_0: { scopes: [ "read:epaye" ] } ]
-      responses:
-        200:
-          body:
-            application/json:
-              type: !include schemas/ChargesSummary.get.schema.json
-              example: !include examples/ChargesSummary.get.json
-        403:
-          body:
-            application/json:
-              type: !include schemas/ErrorCodes.schema.json
-              examples:
-                notOpenStatus:
-                  description: You don't currently have an ePAYE enrolment on this account.
-                  value: |
-                    {
-                      "code" : "INVALID_EMPREF",
-                      "message" : "Provided EmpRef is not associated with your account"
-                    }
-                invalidTaxYear:
-                  description: Incorrect tax year.
-                  value: |
-                    {
-                      "code" : "INVALID_TAXYEAR",
-                      "message" : "Provided Tax Year is incorrect"
-                    }
+
diff --git a/resources/public/api/conf/1.0/examples/Epaye.get.array.json b/resources/public/api/conf/1.0/examples/Epaye.get.array.json
@@ -1,15 +1,17 @@
 {
-  "_embedded": [
+  "empRefs": [
     {
       "empRef": "001/AB00001",
       "_links": {
-        "empRefs": {
-          "href": "/paye-for-employers/"
-        },
-        "total": {
-          "href": "/paye-for-employers/001/AB00001/total"
+        "summary": {
+          "href": "/organisation/paye/001/AB00001/"
         }
       }
     }
-  ]
+  ],
+  "_links": {
+    "self": {
+      "href": "/organisation/paye/"
+    }
+  }
 }
diff --git a/resources/public/api/conf/1.0/examples/Summary.get.json b/resources/public/api/conf/1.0/examples/Summary.get.json
@@ -0,0 +1,17 @@
+{
+  "outstandingCharges": {
+    "amount": 123,
+    "breakdown": {
+      "rti": 100,
+      "nonRti": 23
+    }
+  },
+  "_links" : {
+    "empRefs": {
+      "href": "/organisation/paye/"
+    },
+    "self": {
+      "href": "/organisation/paye/001/AB00001"
+    }
+  }
+}
diff --git a/resources/public/api/conf/1.0/examples/Totals.get.json b/resources/public/api/conf/1.0/examples/Totals.get.json
diff --git a/resources/public/api/conf/1.0/schemas/Definitions.schema.json b/resources/public/api/conf/1.0/schemas/Definitions.schema.json
@@ -1,10 +1,46 @@
 {
   "definitions": {
+    "href": {
+      "type": "string",
+      "description": "URL to endpoint"
+    },
     "empRef": {
       "type": "string",
       "description": "A unique identifier made up of tax office number and tax office reference.",
       "pattern": "^\\w{3}/\\w{7,10}"
     },
+    "epayeLinks": {
+      "type": "object",
+      "description": "An object of links to explore further data.",
+      "properties": {
+        "self": {
+          "type": "object",
+          "description": "Link to the entry endpoint.",
+          "properties": {
+            "href": {
+              "type": "string",
+              "description": "URL to endpoint"
+            }
+          }
+        }
+      }
+    },
+    "empRefLinks": {
+      "type": "object",
+      "description": "An object of links to explore further data.",
+      "properties": {
+        "summary": {
+          "type": "object",
+          "description": "Link to account summary endpoint.",
+          "properties": {
+            "href": {
+              "type": "string",
+              "description": "Link to the summary endpoint."
+            }
+          }
+        }
+      }
+    },
     "links": {
       "type": "object",
       "description": "An object of links to explore further data.",
@@ -70,15 +106,66 @@
         }
       }
     },
+    "outstandingCharges": {
+      "type": "object",
+      "description": "The outstanding charges on account.",
+      "properties": {
+        "amount": {
+          "type": "number",
+          "description": "The outstanding charges on account."
+        } ,
+        "breakdown": {
+          "type": "object",
+          "description": "The breakdown of outstanding charges.",
+          "properties": {
+            "rti": {
+              "type": "number",
+              "description": "The outstanding RTI charges on account."
+            },
+            "nonRti": {
+              "type": "number",
+              "description": "The outstanding Non-RTI charges on account."
+            }
+          }
+        }
+      }
+    },
     "balance": {
       "type": "object",
-      "description": "An object containing the outstanding debits and credits.",
+      "description": "The currently outstanding balance on account.",
+
       "properties": {
+        "credit": {
+          "$ref": "#/definitions/credit"
+        },
         "debit": {
           "$ref": "#/definitions/debit"
+        }
+      }
+    },
+    "summaryLinks": {
+      "type": "object",
+      "description": "An object of links to explore further data.",
+      "properties": {
+        "self": {
+          "type": "object",
+          "description": "Link to account summary endpoint.",
+          "properties": {
+            "href": {
+              "type": "string",
+              "description": "Link account summary endpoint."
+            }
+          }
         },
-        "credit": {
-          "$ref": "#/definitions/credit"
+        "empRefs": {
+          "type": "object",
+          "description": "Link to the entry endpoint endpoint.",
+          "properties": {
+            "href": {
+              "type": "string",
+              "description": "Link to the entry endpoint."
+            }
+          }
         }
       }
     },

diff --git a/resources/public/api/conf/1.0/schemas/Epaye.get.schema.array.json b/resources/public/api/conf/1.0/schemas/Epaye.get.schema.array.json
@@ -2,20 +2,23 @@
   "type": "object",
   "description": "Wrapper object for individual EmpRefs.",
   "properties": {
-    "_embedded": {
+    "empRefs": {
       "type": "array",
       "items": {
         "type": "object",
         "description": "An array of objects which you can use to access further data.",
         "properties": {
           "_links": {
-            "$ref": "Definitions.schema.json#/definitions/links"
+            "$ref": "Definitions.schema.json#/definitions/empRefLinks"
           },
           "empRef": {
             "$ref": "Definitions.schema.json#/definitions/empRef"
           }
         }
       }
+    },
+    "_links": {
+      "$ref": "Definitions.schema.json#/definitions/epayeLinks"
     }
   }
 }
diff --git a/resources/public/api/conf/1.0/schemas/Summary.get.schema.json b/resources/public/api/conf/1.0/schemas/Summary.get.schema.json
@@ -0,0 +1,16 @@
+{
+  "type": "object",
+  "description": "An object containing the account summary.",
+  "properties": {
+    "_links": {
+      "$ref": "Definitions.schema.json#/definitions/summaryLinks"
+    },
+    "outstandingCharges": {
+      "$ref": "Definitions.schema.json#/definitions/outstandingCharges"
+    }
+  },
+  "required": [
+    "outstandingCharges",
+    "_links"
+  ]
+}
diff --git a/resources/public/api/conf/1.0/schemas/Totals.get.schema.json b/resources/public/api/conf/1.0/schemas/Totals.get.schema.json