[YTA-3163] Amended API documentation based on SDST feedback

app/uk/gov/hmrc/epayeapi/router/ApiRouter.scala

@@ -15,7 +15,7 @@
  */
 
 package uk.gov.hmrc.epayeapi.router
-
+import ApiRouter._
 import javax.inject.{Inject, Singleton}
 
 import play.api.routing.Router.Routes
@@ -34,28 +34,6 @@ case class ApiRouter @Inject() (
   getMonthlyStatementController: GetMonthlyStatementController
 ) extends SimpleRouter {
 
-  object TaxOfficeNumber {
-    val regex = "([0-9a-zA-Z]{3})".r
-    def unapply(string: String): Option[String] = {
-      string match {
-        case regex(result) => Some(result)
-        case _ => None
-      }
-    }
-  }
-
-
-  object TaxOfficeReference {
-    val regex = "([0-9a-zA-Z]{7,10})".r
-    def unapply(string: String): Option[String] = {
-      string match {
-        case regex(result) => Some(result)
-        case _ => None
-      }
-    }
-  }
-
-
   val appRoutes = Router.from {
     case GET(p"/") =>
       getEmpRefsController.getEmpRefs()
@@ -73,3 +51,25 @@ case class ApiRouter @Inject() (
   val routes: Routes = prodRoutes.routes.orElse(appRoutes.routes)
 
 }
+
+object ApiRouter {
+  object TaxOfficeNumber {
+    val regex = "(\\d{3})".r
+    def unapply(string: String): Option[String] = {
+      string match {
+        case regex(result) => Some(result)
+        case _ => None
+      }
+    }
+  }
+
+  object TaxOfficeReference {
+    val regex = "([0-9A-Z]{1,10})".r
+    def unapply(string: String): Option[String] = {
+      string match {
+        case regex(result) => Some(result)
+        case _ => None
+      }
+    }
+  }
+}

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

@@ -44,7 +44,7 @@ types:
     get:
       is: [ headers.acceptHeader ]
       displayName: Get access to ePAYE data
-      description: This resource is the entry point to the ePAYE API. It will return a set of URLs, allowing you to access ePAYE data for each account. This will include the employer's ePAYE balance, monthly totals of RTI charges, non-RTI charges and a breakdown of individual charges.
+      description: This resource is the entry point to the ePAYE API. It will return a set of endpoints, allowing you to access ePAYE data for each account. This will include the employer's PAYE balance, monthly totals of RTI charges, non-RTI charges and a breakdown of individual charges.
       (annotations.scope): "read:epaye"
       securedBy: [ sec.oauth_2_0: { scopes: [ "read:epaye" ] } ]
       responses:
@@ -110,7 +110,7 @@ types:
         type: string
         example: "A000001"
       taxYear:
-        description: The tax year...
+        description: The tax year
         type: string
         example: "2017-18"
     get:

resources/public/api/conf/1.0/documentation/overview.md

@@ -7,4 +7,4 @@ This API retrieves data about [Pay As You Earn for employers (ePAYE)](https://ww
 
 This information is intended for use by employers and their agents to check their own calculations of their clients' tax liability.
 
-This version of the API is currently in development and is very likely to be enhanced.
+

resources/public/api/conf/1.0/schemas/Definitions.schema.json

@@ -18,11 +18,15 @@
         },
         "firstDay": {
           "description": "The first day of the tax year",
-          "$ref": "#/definitions/date"
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "example": "2016-04-06"
         },
         "lastDay": {
           "description": "The last day of the tax year",
-          "$ref": "#/definitions/date"
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "example": "2017-04-05"
         }
       },
       "required": [
@@ -44,11 +48,15 @@
         },
         "firstDay": {
           "description": "The first day of the tax month",
-          "$ref": "#/definitions/date"
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "example": "2017-05-06"
         },
         "lastDay": {
           "description": "The last day of the tax month",
-          "$ref": "#/definitions/date"
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "example": "2017-06-05"
         }
       },
       "required": [
@@ -70,12 +78,12 @@
     "taxOfficeNumber": {
       "description": "A tax office number.",
       "type": "string",
-      "pattern": "^\\w{3}$"
+      "pattern": "^\\d{3}$"
     },
     "taxOfficeReference": {
       "description": "A tax office reference.",
       "type": "string",
-      "pattern": "^\\w{7,10}$"
+      "pattern": "^[0-9A-Z]{1,10}$"
     },
     "empRef": {
       "type": "string",

test/uk/gov/hmrc/epayeapi/router/ApiRouterTest.scala

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2018 HM Revenue & Customs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package uk.gov.hmrc.epayeapi.router
+
+
+import uk.gov.hmrc.epayeapi.router.ApiRouter.{TaxOfficeNumber, TaxOfficeReference}
+import uk.gov.hmrc.play.test.UnitSpec
+
+import scala.util.Random
+
+class ApiRouterSpec extends UnitSpec {
+  "ApiRouter.TaxOfficeNumber" should {
+    "extract any 3 digit value" in {
+      for(i <- 100 to 999)
+        TaxOfficeNumber.unapply(i.toString) shouldBe Some(i.toString)
+    }
+
+    "not extract any 2 digit value" in {
+      for(i <- 10 to 99)
+        TaxOfficeNumber.unapply(i.toString) shouldBe None
+    }
+
+    "not extract any 1 digit value" in {
+      for(i <- 1 to 9)
+        TaxOfficeNumber.unapply(i.toString) shouldBe None
+    }
+
+    "not extract any 4 digit or more value" in {
+      for(_ <- 1 to 100) {
+        val i = Random.nextInt(10)
+
+        TaxOfficeNumber.unapply((i * 1000).toString) shouldBe None
+      }
+    }
+
+    "not extract any character values" in {
+      TaxOfficeNumber.unapply("AAA") shouldBe None
+    }
+
+    "not extract any mixed values" in {
+      TaxOfficeNumber.unapply("AA1") shouldBe None
+    }
+  }
+
+  "ApiRouter.TaxOfficeReference" should {
+    "extract any digit value shorter than 10 characters" in {
+      for (length <- 1 to 10)
+        TaxOfficeReference.unapply("1" * length) shouldBe Some("1" * length)
+    }
+
+    "not extract any digit value longer than 10 characters" in {
+      for (length <- 11 to 30)
+        TaxOfficeReference.unapply("1" * length) shouldBe None
+    }
+
+    "extract any uppercase character value shorter than 10 characters" in {
+      for (length <- 1 to 10)
+        TaxOfficeReference.unapply("A" * length) shouldBe Some("A" * length)
+    }
+
+    "not extract any uppercase character value longer than 10 characters" in {
+      for (length <- 11 to 30)
+        TaxOfficeReference.unapply("A" * length) shouldBe None
+    }
+
+    "not extract any lowercase characters" in {
+      for (length <- 1 to 30)
+        TaxOfficeReference.unapply("a" * length) shouldBe None
+    }
+  }
+
+
+}