DESIGN DOCUMENT

FOR
AADHAAR DATA VAULT SERVICE

Sureka Suresh
 Table of Contents
1. Introduction...................................................................................................................................3
1.1 Purpose..................................................................................................................................3
1.2 Scope.....................................................................................................................................3
1.3 Out of Scope..........................................................................................................................3
1.4 Document Ownership............................................................................................................3
2 API/Service Definition....................................................................................................................3
2.1 Risks.......................................................................................................................................4
2.2 Assumptions..........................................................................................................................4
2.3 Issues.....................................................................................................................................4
2.4 Dependencies........................................................................................................................4
2.5 Constraints.............................................................................................................................4
2.6 API/Service Design.................................................................................................................5
3 API/Service Method Definition......................................................................................................5
3.1 POST/ insertUID.....................................................................................................................5
3.1.1 Implementation.............................................................................................................5
3.1.2 Method Design...............................................................................................................5
3.1.3 Summary........................................................................................................................6
3.1.4 Request Schema.............................................................................................................6
3.1.5 Response Schema..........................................................................................................8
3.2 POST/ getUID.........................................................................................................................8
3.2.1 Summary........................................................................................................................9
3.2.2 Request Schema.............................................................................................................9
3.2.3 Response Schema........................................................................................................10
3.3 POST/ getUUID.....................................................................................................................11
3.3.1 Summary......................................................................................................................12
3.3.2 Request Schema...........................................................................................................13
3.3.3 Response Schema........................................................................................................14
3.3.4 Error Handling..............................................................................................................14
3.3.5 Auditing........................................................................................................................15
3.3.6 Logging.........................................................................................................................15
4 API/Service NFR...........................................................................................................................15
4.1 Security................................................................................................................................15
4.2 Auditing...............................................................................................................................15
4.3 Performance........................................................................................................................15

Service Design Document Page 1

 4.4 Exception and Error Handling..............................................................................................15
4.5 Application Monitoring........................................................................................................16
4.6 Batch Processing and Scheduling.........................................................................................16
4.7 Build and Deployment Solution...........................................................................................16
4.7.1 Code Versioning...........................................................................................................16
4.7.2 Continuous Integration................................................................................................16
4.8 Tools and Technologies........................................................................................................16
4.8.1 Development Tools......................................................................................................16
4.8.2 Technologies................................................................................................................16
4.8.3 Environment................................................................................................................16
5 Testing..........................................................................................................................................16
5.1 Testing Approach.................................................................................................................16
5.2 Functional Testing................................................................................................................17
5.3 Non-Functional testing.........................................................................................................17
5.4 Testing Tools.........................................................................................................................17
5.5 Mocking frameworks...........................................................................................................17

Service Design Document Page 2

1. Introduction

1.1 Purpose
The purpose of this document is to provide the detailed design for the Portal Experience API along
with the interaction methods/operations, protocols, and Quality of Service (QoS). It also provides
request and response structure. It also details the non-functional requirements design like debug
logging, error/exception handling, Security.

1.2 Scope
This document only covers details around Portal API that will be used to perform the following
operations at DataVault API Level.

● POST Insert UID Details

o Requesting to WEB API to Insert Aadhaar Number Into Data Vaults
● POST Get UID Details
o Requesting to WEB API to Get Aadhaar Number From Data Vault.Post Passport
Verification
● POST Get UUID Details
o Requesting to WEB API to Get UUID from Data Vault against UID / UIDToken.

1.3 Out of Scope

● Any changes to existing business processes required to support the data exchanges between
end systems.
● Any other integrations other than the above mentioned API’s calls under the section 1.2 is
out of scope

1.4 Document Ownership

This document and the contract of the Service Operation it defines is owned by:
 The Delivery Team during delivery phases
 The Support Team following the successful go live of the API

2 API/Service Definition
API/Service Title Experience API to perform the DataVault Operations
API/Service Name x-portal-aadhar-datavault-api.raml
API/Service Version 1.0

Brief Description This API exposes Consumer operations –

- To POST Insert Aadhar Number
- To POST get UID for UUID/UIDToken

Service Design Document Page 3

 - To POST get UUID for UID/UIDToken
Summary of Methods Following are the operations exposed through this API:
 post/getUID– Posts the getUID details to target system via
Syntizen DataVault system API.
 Post/insertUID – Posts the insertUID details to target system via
Syntizen DataVault system API
 Post/getUUID -Posts the getUUID details to target system via
Syntizen DataVault system API

Criticality High
Layer/Category System
Usage Real Time
Base URI Dev:http://Mulesoft-Dev-743329365.ap-south-1.elb.amazonaws.com/
api/1.0/ux/{resoucename}
SIT:https://sit-api.fsbl.in/api/1.0/ux/{resoucename}
UAT: https://uat-api.fsbl.in/api/1.0/ux/{resoucename}
PROD : https://api.fivestar.in/api/1.0/ux/{resoucename}

Transport Protocol(s) HTTP

Port number:
Dev: 8192
SIT: 8192
UAT: 8192
PROD: 8192
Service Level Access (SLA) SLA is valid if there are no re-connection attempts required to connect
to downstream system. If a re-connection is attempted, the response
time will include the frequency and retry delay.

2.1 Risks
FIVESTAR will be using Spring security module to achieve Basic Authentication to secure the APIs.
Authentication happens via Code which is against standard Mulesoft's suggestion to have the
authentication at the API Gateway level, since API manager license is not procured by FiveStar.

2.2 Assumptions

1. API’s request and response will be in JSON format.

2. The API receives data which is already syntactically and semantically validated.
3. All dependencies are resolved before the start of the development.

2.3 Issues
1. If system API is down, it will try re-connecting based on a defined configuration.
2. API Dashboard not privileged, hence the client won’t be able to check the traffic and the status code
per requests.

2.4 Dependencies
1. Fivestar to provide access to the Data Vault API for various integration processes.

Service Design Document Page 4

2.5 Constraints
NA

2.6 API/Service Design

This API defines multiple operations to interact with the target system services for getting the
requested customer details.

3 API/Service Method Definition

3.1 POST/ insertUID

3.1.1 Implementation
 Common logger framework should be used for standard logging across all the entry, process and exit
point as per the best practices.
 All component naming should be done as per the best practices.
 This API method accepts encrypted request over HTTP endpoint.
 The request is validated against the mapping sheet and an error response is returned if validation
fails.
 The timeout properties on experience API should be configurable. Actual value will be configured for
production based on performance testing.
 All sensitive properties should be secured using AES encryption and CBC mode.

3.1.2 Method Design

Following is the list of recommended Mule ESB components to be used for this method.
 HTTP Listener – to configure HTTP inbound endpoint for this API operation.
 Reference Exception Strategy – to invoke a global shared exception strategy defined in the
application.
 Secure Property Placeholder – to encrypt the sensitive properties.
 HTTP Requester – to invoke the System API.
 Data Weave – to transform the response from S- API.
 Flow/Private-Flow/Sub-Flow – to implement the actual business logic.

Service Design Document Page 5

  Set Payload – to set payload message when required.
 Logger Framework – to do standard logging
 Choice – to validate Client Credentials.
 RAML Library – to describe request and response structure for this API.
 RAML – to define API contracts. This will use the JSON schema internally.
 APIkit Console – to simulate and test the API contract
 APIkit Router – to route API call to the correct operations

3.1.3 Summary
This API operation is responsible to Post the Insert UID details via Data Vault. The Post operation
covers the following use cases:
 POST Insert Aadhaar Number into Data Vault
The experience API will be invoked by the request payload to post insert UID Details

The following resource of System API will invoked

● /insertUID

The below parameters will be picked from the secured properties (<project-name>-{env}-secure-
properties.yaml, (<project-name>-{env}-properties.yaml, (<project-name>-common-properties.yaml)
file before invoking the Data Vault System
 System API configuration details from (<project-name>-{env}-properties.yaml)
 System api basic authentication details, client id and client secret (<project-name>-{env}-secure-
properties.yaml)
 System api call retry configuration (<project-name>common-properties.yaml)

The following response scenarios handled at the ESB:

a. SUCCESS scenario: Data Vault details successfully fetched from the system api, and the system api
response will be captured and transformed to return to the consumer API.
b. Data error scenario: Validation error at the system API, return the specific error response to the
consumer API.
c. End System Error Scenario: In case end system is down or unreachable, it will return back the error to
the consumer API, along with the error code.

3.1.4 Request Schema

There is no request schema defined as such, because the request which comes to the experience api
is in the encrypted format and is converted to byte using fromBase64 and then is decrypted using
the AES/CBC algorithm using IV and Key in the process api.

After decrypting the payload, convert the encrypted file using jar files provided by Syntizen
Technologies Pvt. Ltd. and send it to the System API.

Refer the “x-portal-aadhar-datavault-api” project in Anypoint Design Center for schema definition. A
quick link for the project is as follows.

Service Design Document Page 6

https://anypoint.mulesoft.com/exchange/3310beae-d70b-4ed2-8c88-18a9a88c900c/x-portal-
aadhar-datavault-api/

Note: you would require Fivestar Anypoint Platform account to be able to access the request schema.
Canonical Model for request schema is not applicable.

Decryption method is created using the Java code to decrypt.

Note:- IV key is attached at the end of encrypted payload string after . (dot), In case of any . (dot)
generated in encrypted payload will be the issue while doing decryption

Java Files:

Attribute Data Types Description

UIDToken String Optional

AadhaarNo String Aadhaar Number

APPKey String Data Vault App Key

String(50) Unique Reference number

Rrn
for each transaction

Request

"UIDToken": "",

"UID": "123412341234",

"AppKey": "LNFVN-FRXWZ-XXUCT-XZXDO",

"Rrn": "310711568052840183"

Encrypted request :

+qIBZhyJZ6w5h0+TueXCHoBjyqZmQi3i3oqkSFSKQ4ed9MFof0A682qlx5gl0jQfe1xbkFirR4y33GgrFMML
+XZUVrKlkLOF9p+cWObJ4pKdw4OT1X1aZIkV/eQcDIdk0jAd95Sx25Pkvw9oJrqscQ==

Service Design Document Page 7

3.1.5 Response Schema

Attribute Data Types Description

String 1 – Success
STATUS
0 - Failure

String Unique Identifier ( Note :

UUID Will be empty
in case of failure )

String Error Message for the failure

ERRORMSG
Response

Response

"RESPONSE": {

"STATUS": "1",

"UUID": "5911108950349",

"UIDTOKEN": "",

"MASKEDUID": "********1234",

"ERRORCODE": "SYNDV00",

"ERRORMSG": ""

Refer the “x-portal-aadhar-datavault-api” project in Anypoint Design Center for schema definition. A
quick link for the project is as follows.

https://anypoint.mulesoft.com/exchange/3310beae-d70b-4ed2-8c88-18a9a88c900c/x-portal-
aadhar-datavault-api/

3.2 POST/ getUID

Service Design Document Page 8

3.2.1 Summary
This API operation is responsible to Post the get Aadhar Number from Data Vault using User
Identifier UID Token. In case UID Token exists in Data Vault the respective Aadhar number will be
returned. The Post operation covers the following use cases:
 POST get Aadhaar Number into Data Vault
The experience API will be invoked by the request payload to post get UID Details

The following resource of System API will invoked

● /getUID

The below parameters will be picked from the secured properties (<project-name>-{env}-secure-
properties.yaml, (<project-name>-{env}-properties.yaml, (<project-name>-common-properties.yaml)
file before invoking the Data Vault System
 System API configuration details from (<project-name>-{env}-properties.yaml)
 System api basic authentication details, client id and client secret (<project-name>-{env}-secure-
properties.yaml)
 System api call retry configuration (<project-name>common-properties.yaml)

The following response scenarios handled at the ESB:

d. SUCCESS scenario: Data Vault details successfully fetched from the system api, and the system api
response will be captured and transformed to return to the consumer API.
e. Data error scenario: Validation error at the system API, return the specific error response to the
consumer API.
f. End System Error Scenario: In case end system is down or unreachable, it will return back the error to
the consumer API, along with the error code.

3.2.2 Request Schema

There is no request schema defined as such, because the request which comes to the experience api
is in the encrypted format and is converted to byte using fromBase64 and then is decrypted using
the AES/CBC algorithm using IV and Key in the process api.

Service Design Document Page 9

After decrypting the payload, convert the encrypted file using jar files provided by Syntizen
Technologies Pvt. Ltd. and send it to the System API.

Attribute Data Types Description

UUID String Unique Identifier

int 1 – UUID
UIDType
2 – UID Token

APPKey String Data Vault App Key

String(50) Unique Reference number

Rrn
for each transaction

Request

"UUID": "5911108950349",

"UIDType": "1",

"AppKey": "LNFVN-FRXWZ-XXUCT-XZXDO",

"Rrn": "310711332385314560"

Encrypted Request:

YdJzN9MV1B8dVZog9+bRazjyRdkuUbsSjUiJXWJ9KTLuVyusOTfSVwpx1OIaed1qcf/
DhZVrBvIjEXqqGEMMtz0bk/
WZ7Tr3T16XbZ8UF9P+BRNVmd8Egn6SOlSJWCB+Uzn5kdwTjCU61qde3Sn15A==

3.2.3 Response Schema

Attribute Data Types Description

String 1 – Success
STATUS
0 - Failure

String Unique Identifier ( Note :

UUID Will be empty
in case of failure )

Service Design Document Page 10

 String Error Message for the failure
ERRORMSG
Response

Response

"RESPONSE": {

"STATUS": "1",

"UID": "123412341234",

"UIDTOKEN": "",

"MASKEDUID": "",

"ERRORCODE": "SYNDV00",

"ERRORMSG": ""

Refer the “x-portal-aadhar-datavault-api” project in Anypoint Design Center for schema definition. A
quick link for the project is as follows.

https://anypoint.mulesoft.com/exchange/3310beae-d70b-4ed2-8c88-18a9a88c900c/x-portal-
aadhar-datavault-api/

3.3 POST/ getUUID

Service Design Document Page 11

3.3.1 Summary
This API operation is responsible to Post the get Aadhar Number from Data Vault using User
Identifier UUID Token. In case UUID Token exists in Data Vault the respective Aadhar number will be
returned. The Post operation covers the following use cases:
 POST get Aadhaar Number into Data Vault
The experience API will be invoked by the request payload to post get UUID Details

The following resource of System API will invoked

● /getUUID

The below parameters will be picked from the secured properties (<project-name>-{env}-secure-
properties.yaml, (<project-name>-{env}-properties.yaml, (<project-name>-common-properties.yaml)
file before invoking the Data Vault System
 System API configuration details from (<project-name>-{env}-properties.yaml)
 System api basic authentication details, client id and client secret (<project-name>-{env}-secure-
properties.yaml)
 System api call retry configuration (<project-name>common-properties.yaml)

The following response scenarios handled at the ESB:

g. SUCCESS scenario: Data Vault details successfully fetched from the system api, and the system api
response will be captured and transformed to return to the consumer API.

Service Design Document Page 12

 h. Data error scenario: Validation error at the system API, return the specific error response to the
consumer API.
i. End System Error Scenario: In case end system is down or unreachable, it will return back the error to
the consumer API, along with the error code.

3.3.2 Request Schema

There is no request schema defined as such, because the request which comes to the experience api
is in the encrypted format and is converted to byte using fromBase64 and then is decrypted using
the AES/CBC algorithm using IV and Key in the process api.

After decrypting the payload, convert the encrypted file using jar files provided by Syntizen
Technologies Pvt. Ltd. and send it to the System API.

Attribute Data Types Description

String Unique Identifier (Aadhaar

UID
Number) / UIDToken

int UIDToken - 2
UIDType
UID - 3

APPKey String Data Vault App Key

String(50) Unique Reference number

Rrn
for each transaction

Request

"UID": "123412341234",

"UIDType": "3",

"AppKey": "LNFVN-FRXWZ-XXUCT-XZXDO",

"Rrn": "310711047530485400"

Encrypted Request:

Service Design Document Page 13

SVap9rPp1LIQxmtXHgQ04Ygphvek/
lts4wRB+PKXzkV+RqJazsF0EImRlfWrYrL6e1xbkFirR4y33GgrFMML+c/bcHYo/
KJs867FxQYD+mE9snkiumZdwFIqz2vndnou4PhP8CvXax9SNru21mUI7g==

3.3.3 Response Schema

Attribute Data Types Description

String 1 – Success
STATUS
0 - Failure

String Unique Identifier ( Note :

UUID Will be empty
in case of failure )

String Error Message for the failure

ERRORMSG
Response

Response

"RESPONSE": {

"STATUS": "1",

"UUID": "5911108950349",

"UIDTOKEN": "",

"MASKEDUID": "********1234",

"ERRORCODE": "SYNDV00",

"ERRORMSG": ""

Refer the “x-portal-aadhar-datavault-api” project in Anypoint Design Center for schema definition. A
quick link for the project is as follows.

https://anypoint.mulesoft.com/exchange/3310beae-d70b-4ed2-8c88-18a9a88c900c/x-portal-
aadhar-datavault-api/

3.3.4 Error Handling

 For any error, a standard HTTP error code should be return with corresponding message.
 For any process/system api connectivity issues, the particular error message with the respective error
code is sent as response. Below is the error response structure to be formed if any error occurs:

Service Design Document Page 14

 Target Source

error <root tag>

source Name of the source system

target Name of the Karza system

errorCode error code number

message error message

description Detailed description of the error

timeStamp Current datetime in yyyy-MM-dd HH:mm:ssZ format

3.3.5 Auditing
NA

3.3.6 Logging
Following information will be implemented and captured in Database in this API:
 Application Name
 Flow Name
 Request Id
 Message Id
 Log Message
Payload should never be logged. If business requires some key information to be logged such as
correlation Id, it should be logged using custom logger framework but ensure not to log any sensitive
data such as customer email, contact details or card details.

4 API/Service NFR

4.1 Security
Following security shall be implemented/configured in this API:
 The API shall be private and should use HTTP i.e., expose internally using port 8192.
Any system API credentials must be encrypted and picked from the secure property files.

4.2 Auditing
NA

4.3 Performance
 Mule API makes multiple re-connection attempt due to target web service connection issues, the
overall time for API to return a response will be multiplied based on the configuration.
 The overall response time depends on how long downstream API takes to serve the request.

Service Design Document Page 15

4.4 Exception and Error Handling
Global Reference Exception strategy is used for exception and error handling. A set of common
exceptions that need to be handled are declared in the global exception handling block and all
exceptions and error originated in the flow will be referenced or passed to this global exception
strategy block. Custom error formed in error xml will be sent back to the caller.

4.5 Application Monitoring

Additional API transactions details will be captured as part of logging will be used for future
reporting.

Manual monitoring and health check will be part of the support activity carried out by the support
team. Maven as a build tool will be used to standardize on build best practices, reduce
dependencies, simplify continuous integration and easily share projects between developers.

4.6 Batch Processing and Scheduling

NA

4.7 Build and Deployment Solution

4.7.1 Code Versioning

GitHub is used for software configuration management. Access to GitHub is provided by Fivestar.

4.7.2 Continuous Integration

NA

4.8 Tools and Technologies

4.8.1 Development Tools

 Anypoint Studio 7.11 with Mule 4.4 runtime - used for all mule application development
 Anypoint Design Center - will be used to design API.
 Anypoint Runtime Manager – for application deployment
 Maven – for defining the application dependencies
 Anypoint Exchange – used to maintain all MuleSoft API assets.

4.8.2 Technologies
 Data Weave expression language
 JSON

4.8.3 Environment
Refer to the section 2.6 under below link for quick reference of HLD for details related to
environments to be used.

5 Testing

Service Design Document Page 16

5.1 Testing Approach
The testing for this API shall cover the following:
 The API shall be accessible only using HTTP port 8085.
 The request and response structure are aligned with the schema mentioned in this document.
 Logging should be as per the logging framework best practices.
 Postman to be used for functional testing.
 MUnits will be written for unit testing.
 System Integration Testing (SIT) will be performed by Whishworks testing team for the possible test
cases which can be executed

5.2 Functional Testing

 Testing and verification of all use cases mentioned in 1.2 section.
 All mapping rules should be executed as per the mapping sheet given in this document.

5.3 Non-Functional testing

NA

5.4 Testing Tools

 Postman
 Soap UI

5.5 Mocking frameworks

Munit

***End of Document***

Service Design Document Page 17