API Semantics

This section explains the semantics of our REST API. All our APIs are based on RESTful Semantics. All our APIs have a common response format.

All Quickplay APIs supports:

• HTTP protocol version 1.1 or later.
• TLS v1.2 and higher, no plain HTTP access.
• Some APIs requires Mutual TLS Authentication using a client certificate.
• JSON for data exchange.

RESTful Semantics

All Quickplay APIs confirm to Representational State Transfer (REST) architectural style. The following are the REST methods used in our APIs and their uses:

Method	Business Operation
GET	Lookup, search or query object/entity
POST	Create new object/entity (single object or collection of objects in bulk)
PUT	Update existing object/entity (single object or collection of objects in bulk)
DELETE	Delete existing object/entity

HTTP Response Format

Standard Response Fields

Field	Data Type	Description
header	<Object>	Standard header object.
header -> code	Integer	Response Code: 0 – Success -1 – Failure
header -> message	String	Response Message. Optional for failure response. For success response this should have the success message displayed to the end user.
header -> system_time	Timestamp	Server time in Unix Epoch Time in Milliseconds format
header -> start	Integer	Start index in a paginated response
header -> rows	Integer	Number of rows returned in a paginated response
header -> count	Integer	Total number of results matched in a multi-valued respose
//JSON Object	Object	Response Object/Entity in JSON format for single-valued response
//Array of JSON Object	Object Array	Array of Object/Entity in JSON format for multi-valued response
errors	Object	Error object
errors[n]->code	String	Error Code. Refer Standard Error Code Format
errors[n]->description	String	Error Description

Single value success response

{
    "header": {
        "source": "<Source Micro-service Name>",
        "code": "0",
        "message": "Success",
        "system_time": 1558041284123,
    },
    "data": {
        //JSON Object
    }
}

Multi-value success response

{
    "header": {
        "source": "Micro-service Name",
        "code": "0",
        "message": "Success",
        "system_time": 1558041284123,
        "start": 0,
        "rows": 10,
        "count": 100
    },
    "data": [
        //Array of JSON Objects
    ]
}

Success Response - Plain acknowledgement

{
    "header": {
        "source": "<Source Micro-service Name>",
        "code": "0",
        "message": "Success",
        "system_time": 1558041284123
    }
}

Failure Response - Plain acknowledgement

{
    "header": {
        "source": "<Source Micro-service Name>",
        "code": "-1",
        "message": "Failure Message",
        "system_time": 1558041284123,
        "errors": [
            {
                "code": "40010301",
                "description": "Error Description 1"
            },
            {
                "code": "40010303",
                "description": "Error Description"
            }
        ]
    }
}

Failure Response with a data

{
    "header": {
        "source": "<Source Micro-service Name>",
        "code": "-1",
        "message": "Failure Message",
        "system_time": 1558041284123
        "errors": [
            {
                "code": "40010301",
                "description": "Error Description 1"
            },
            {
                "code": "40010303",
                "description": "Error Description"
            }
        ]
    },
    "data": [
        //Array of JSON Object
    ]
}

HTTP Response Codes

HTTP Response Code	Response Condition
200 OK	- Successful Response - Failures other than 401, 403, 404 and 429. The exact failure reason code and message can be found in the JSON Response Header.
401 Unauthorized	Whenever a API requires a valid user token/OVAT and if it is not provided in the request
403 Forbidden	Whenever a API requires a valid user token/OVAT and if the provided session Token/OVAT is invalid or expired or the OVAT signature mismatch
404 Not Found	If the requested URL is not having an equivalent service end point
429 Too Many Requests	Exceeded the API throttling limit

Standard Error Code Format

All micro service error code follow the following 8 digit numeric pattern

TABCXYPQ

T	ABC	XY	PQ
Type of error. 3 - 3rd party application errors 4 - Validation errors 5 - Internal error 6 - Security errors	Unique ID of a microservice. All microservices has an unique identifier.	API sequence number for a micro service. It starts with 01.	Error Sequence Number. It starts with 01 for an API for a specific type.

Example

For error code 40010305,

• The error is of type 4 indicating that this is a validation failure error.
• The error is for microservice ID 001
• The error is for API number 3
• The error is for the validation error sequence 5.

info

The response header->code attribute indicates whether the response is success or failure.

• 0 - Success
• -1 - Failure

The actual error codes returned by the API is available in the attribute errors[n]->code.

{
    "header": {
        "source": "<Source Micro-service Name>",
        "code": "-1",
        "message": "Failure Message",
        "system_time": 1558041284123,
        "errors": [
            {
                "code": "40010305",
                "description": "Error Description 1"
            }
        ]
    }
}