Merge pull request #30 from monamok/feat/guidelines_alignment_errors_…

…and_camelCase

guidelines alignment errors and camel case

code/API_definitions/CAMARA/number_verification.yaml

@@ -14,7 +14,7 @@ info:
     This API currently provides two endpoints where both require a **3-legged token** and authentication via **mobile network** (excluding for example by SMS/OTP or user/password as an authentication method):
     - The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**.
     - The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider.
-  version: 0.2.0
+  version: 0.3.0
   termsOfService: http://example.com/terms/
   contact:
     name: API Support
@@ -74,17 +74,17 @@ paths:
               schema:
                 $ref: '#/components/schemas/NumberVerificationMatchResponse'
         '400':
-          $ref: '#/components/responses/InvalidArgument'
+          $ref: '#/components/responses/Generic400'
         '401':
-          $ref: '#/components/responses/Unauthenticated'
+          $ref: '#/components/responses/Generic401'
         '403':
-          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
+          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
         '500':
-          $ref: '#/components/responses/Internal'
+          $ref: '#/components/responses/Generic500'
         '503':
-          $ref: '#/components/responses/Unavailable'
+          $ref: '#/components/responses/Generic503'
         '504':
-          $ref: '#/components/responses/Timeout'
+          $ref: '#/components/responses/Generic504'
       security:
         - three_legged:
           - number-verification-verify-read
@@ -118,17 +118,17 @@ paths:
               schema:
                 $ref: '#/components/schemas/NumberVerificationShareResponse'
         '400':
-          $ref: '#/components/responses/InvalidArgument'
+          $ref: '#/components/responses/Generic400'
         '401':
-          $ref: '#/components/responses/Unauthenticated'
+          $ref: '#/components/responses/Generic401'
         '403':
-          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied'
+          $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403'
         '500':
-          $ref: '#/components/responses/Internal'
+          $ref: '#/components/responses/Generic500'
         '503':
-          $ref: '#/components/responses/Unavailable'
+          $ref: '#/components/responses/Generic503'
         '504':
-          $ref: '#/components/responses/Timeout'
+          $ref: '#/components/responses/Generic504'
       security:
         - three_legged:
           - number-verification-share-read
@@ -147,32 +147,32 @@ components:
     PhoneNumber:
       type: object
       properties:
-        phone_number:
+        phoneNumber:
           description: A phone number belonging to the user. 'E164 with +' format
           type: string
           example: '+346661113334'
     HashedPhoneNumber:
       type: object
       properties:
-        hashed_phone_number:
+        hashedPhoneNumber:
           description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format
           type: string
           example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba
     NumberVerificationMatchResponse:
       type: object
       description: Number verification result
       required:
-        - device_phone_number_verified
+        - devicePhoneNumberVerified
       properties:
-        device_phone_number_verified:
+        devicePhoneNumberVerified:
           $ref: '#/components/schemas/DevicePhoneNumberVerified'
     NumberVerificationShareResponse:
       type: object
       description: Number verification share result
       required:
-        - device_phone_number
+        - devicePhoneNumber
       properties:
-        device_phone_number:
+        devicePhoneNumber:
           $ref: '#/components/schemas/DevicePhoneNumber'
     DevicePhoneNumber:
       description: The device phone number associated to the access token. 'E164 with +' format
@@ -181,37 +181,24 @@ components:
     DevicePhoneNumberVerified:
       description: Number verification. True, if it matches
       type: boolean
-    ModelError:
+    ErrorInfo:
       type: object
       required:
         - status
+        - code
         - message
       properties:
         status:
           type: integer
-          minimum: 400
-          maximum: 599
           description: HTTP response status code
+        code:
+          type: string
+          description: Code given to this error
         message:
           type: string
-          description: A human readable description of what the event represent
-    PhoneNumberVerificationPermissionDenied:
-      allOf:
-        - type: object
-          required:
-            - code
-          properties:
-            code:
-              type: string
-              enum:
-                - PERMISSION_DENIED
-                - NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
-                - NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT
-              default: PERMISSION_DENIED
-              description: Client does not have sufficient permissions to perform this action.
-        - $ref: '#/components/schemas/ModelError'
+          description: Detailed error description
   responses:
-    InvalidArgument:
+    Generic400:
       description: Problem with the client request
       headers:
         x-correlator:
@@ -221,25 +208,12 @@ components:
       content:
         application/json:
           schema:
-            allOf:
-              - type: object
-                required:
-                  - code
-                properties:
-                  code:
-                    type: string
-                    enum:
-                      - INVALID_ARGUMENT
-                    default: INVALID_ARGUMENT
-                    description: Client specified an invalid argument, request body or query param.
-              - $ref: '#/components/schemas/ModelError'
-          examples:
-            response:
-              value:
-                status: 400
-                code: INVALID_ARGUMENT
-                message: Client specified an invalid argument, request body or query param
-    Unauthenticated:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 400
+            code: INVALID_ARGUMENT
+            message: Client specified an invalid argument, request body or query param
+    Generic401:
       description: Authentication problem with the client request
       headers:
         x-correlator:
@@ -249,25 +223,12 @@ components:
       content:
         application/json:
           schema:
-            allOf:
-              - type: object
-                required:
-                  - code
-                properties:
-                  code:
-                    type: string
-                    enum:
-                      - UNAUTHENTICATED
-                    default: UNAUTHENTICATED
-                    description: Request not authenticated due to missing, invalid, or expired credentials.
-              - $ref: '#/components/schemas/ModelError'
-          examples:
-            response:
-              value:
-                status: 401
-                code: UNAUTHENTICATED
-                message: Request not authenticated due to missing, invalid, or expired credentials
-    PhoneNumberVerificationPermissionDenied:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 401
+            code: UNAUTHENTICATED
+            message: Request not authenticated due to missing, invalid, or expired credentials
+    PhoneNumberVerificationPermissionDenied403:
       description: |-
         Client does not have sufficient permission.
         In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
@@ -281,14 +242,24 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/PhoneNumberVerificationPermissionDenied'
+            $ref: '#/components/schemas/ErrorInfo'
           examples:
-            response:
+            PermissionDenied:
+              value:
+                status: 403
+                code: PERMISSION_DENIED
+                message: Client does not have sufficient permissions to perform this action
+            UserNotAuthenticatedByMobileNetwork:
               value:
                 status: 403
                 code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
                 message: Client must authenticate via the mobile network to use this service
-    Internal:
+            InvalidTokenContext:
+              value:
+                status: 403
+                code: HOME_DEVICES_QOD.INVALID_TOKEN_CONTEXT
+                message: Phone number cannot be deducted from access token context
+    Generic500:
       description: Server error
       headers:
         x-correlator:
@@ -298,25 +269,12 @@ components:
       content:
         application/json:
           schema:
-            allOf:
-              - type: object
-                required:
-                  - code
-                properties:
-                  code:
-                    type: string
-                    enum:
-                      - INTERNAL
-                    default: INTERNAL
-                    description: Unknown server error.Typically a server bug.
-              - $ref: '#/components/schemas/ModelError'
-          examples:
-            response:
-              value:
-                status: 500
-                code: INTERNAL
-                message: Server error
-    Unavailable:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 500
+            code: INTERNAL
+            message: Server error
+    Generic503:
       description: Service unavailable. Typically the server is down.
       headers:
         x-correlator:
@@ -326,25 +284,12 @@ components:
       content:
         application/json:
           schema:
-            allOf:
-              - type: object
-                required:
-                  - code
-                properties:
-                  code:
-                    type: string
-                    enum:
-                      - UNAVAILABLE
-                    default: UNAVAILABLE
-                    description: Request timeout exceeded
-              - $ref: '#/components/schemas/ModelError'
-          examples:
-            response:
-              value:
-                status: 503
-                code: UNAVAILABLE
-                message: Service unavailable
-    Timeout:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 503
+            code: UNAVAILABLE
+            message: Service unavailable
+    Generic504:
       description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
       headers:
         x-correlator:
@@ -354,24 +299,11 @@ components:
       content:
         application/json:
           schema:
-            allOf:
-              - type: object
-                required:
-                  - code
-                properties:
-                  code:
-                    type: string
-                    enum:
-                      - TIMEOUT
-                    default: TIMEOUT
-                    description: Request timeout exceeded
-              - $ref: '#/components/schemas/ModelError'
-          examples:
-            response:
-              value:
-                status: 504
-                code: TIMEOUT
-                message: Request timeout exceeded. Try later.
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 504
+            code: TIMEOUT
+            message: Request timeout exceeded. Try later.
 externalDocs:
   description: Project documentation at CAMARA
   url: https://github.com/camaraproject/NumberVerification

documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md

@@ -59,9 +59,9 @@ Following table defines API endpoints of exposed REST based for Number Verificat
 
 | **Request to verify a number** |
 | -------------------------- |
-| **HTTP Request**<br> POST /number-verification/v0/verify<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> **One of:** <br> **phone_number**: A phone number belonging to the user. 'E164 with +' format.<br> **hashed_phone_number**: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format.
+| **HTTP Request**<br> POST /number-verification/v0/verify<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> **One of:** <br> **phoneNumber**: A phone number belonging to the user. 'E164 with +' format.<br> **hashedPhoneNumber**: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format.
 
- <br>**Response**<br> **200: OK**<br>  Response body: <br>**device_phone_number_verified** : Boolean <br> **400:** **INVALID_ARGUMENT** <br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br> **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
+ <br>**Response**<br> **200: OK**<br>  Response body: <br>**devicePhoneNumberVerified** : Boolean <br> **400:** **INVALID_ARGUMENT** <br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br> **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL**<br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
 <br>
 
 <br>
@@ -70,7 +70,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat
 | -------------------------- |
 | **HTTP Request**<br> GET /number-verification/v0/device-phone-number<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> No body
 
- <br>**Response**<br> **200: OK**<br>  Response body: <br>**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format. <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br>  **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL** <br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
+ <br>**Response**<br> **200: OK**<br>  Response body: <br>**devicePhoneNumber** : The device phone number associated to the access token. 'E164 with +' format. <br> **400:** **INVALID_ARGUMENT**<br> **401:** **UNAUTHENTICATED** <br> **403:** **PERMISSION_DENIED** <br> **403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK** <br>  **403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT** <br> **500:** **INTERNAL** <br> **503:** **UNAVAILABLE**<br> **504:** **TIMEOUT**<br>
 <br>
 
 <br>
@@ -109,14 +109,14 @@ Please note, the credentials for API authentication purposes need to be adjusted
 
 | Snippet 1. Request code  |
 | ----------------------------------------------- |
-| curl -X 'POST' `https://sample-base-url/number-verification/v0/verify`   <br>    -H 'accept: application/json' <br>    -H 'Content-Type: application/json'<br>    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."<br>    -d '{ "hashed_phone_number": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"}'  |
-| The response will be: <br> 200 <br>   -d '{ "device_phone_number_verified": true }'|
+| curl -X 'POST' `https://sample-base-url/number-verification/v0/verify`   <br>    -H 'accept: application/json' <br>    -H 'Content-Type: application/json'<br>    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."<br>    -d '{ "hashedPhoneNumber": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"}'  |
+| The response will be: <br> 200 <br>   -d '{ "devicePhoneNumberVerified": true }'|
 <br>
 
 | Snippet 2. Validate code  |
 | ----------------------------------------------- |
 | curl -X 'GET' `https://sample-base-url/number-verification/v0/device-phone-number`   <br>    -H 'accept: application/json' <br>    -H 'Content-Type: application/json'<br>    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."<br> |
-| The response will be: <br> 200 <br>   -d '{ "device_phone_number": "+346661113334" }'|
+| The response will be: <br> 200 <br>   -d '{ "devicePhoneNumber": "+346661113334" }'|
 <br>