Response Basics

All submitted requests have corresponding responses that indicate the status of the requests. The data contained in the responses will depend on the request that was made. In this section, we will look at the basic structure of response data.

Response Structure

As stated earlier, a response data is returned after a request is made. The response data is made up of two main sections. These are the handshake and data sections. The basic structure of the response object is shown as follows.

{
    "handshake" : {
	  
    },
    "data": {
	  
    }
}

The handshake section of the response contains information that indicate the status of the request whiles the data section contains information after processing the request. The information in the data depends on the request that was submitted.

Request Handshake

When a request is submitted, the server performs validation to ensure that all required fields are provided and valid. If the HTTP status code set for the response is not 200 OK, then it implies that the request failed. However, if the HTTP status code is 200 OK, it does not guarantee that the request was successful.

The handshake section of the response complements the HTTP status identifiers. It is used to describe request errors that are not available in the HTTP status codes. When the HTTP status code is 200 OK, applications will still need to make further check in the handshake section of the response to ensure that the handshake id is 0 HSHK_OK.

{
    "handshake" : {
        "id": 0,
        "label" : "HSHK_OK"
    },
    "data": {
    }
}

As said, if request validation fails, there is the need to return a status identifier that indicates the cause of the error. Since HTTP status codes do not provide all the application error codes, the handshake section is used to provide application specific error codes that give enough information with regards to request errors.

When a request is submitted, applications should first check the HTTP status code. If the HTTP status code is different from 200, then request validation failed. The HTTP status code returned will need to be used to interpret the cause of the error.

If the response has HTTP status code 200, applications will still need to check the request handshake status code. This is because there are some application status codes that are not provided by HTTP status codes.

Suppose an account making a request is inactive. Then there will be the need to abort the request and indicate that the specified account is not active. Such status does not exist in the HTTP status codes and therefore this information will be set in the handshake section of the response object.

{
    "handshake" : {
        "id": 1408,
        "label" : "HSHK_ERR_ACCT_INACTIVE"
    },
    "data": {
    }
}

As indicated earlier, the Request Handshake status codes supplement the HTTP status codes. Like the HTTP status code 200, a Request Handshake status 0 indicates that the request was accepted for processing.

Response Data

Most requests submitted to the server will lead to some related response data being returned to the calling application.

For example, when a request is made for credit balance, the server will return the related data to the calling application by setting the balance information in the data section of the response object.

{
    "handshake" : {
        "id": 0,
        "label" : "HSHK_OK"
    },
    "data": {
        "balance": 2432,
        "model": "quantity",
        "currencyName": null,
        "currencyCode": null
    }
}

Since the actual data returned depends on the request made, we will defer further discussions on the response data to subsequent sections that take a look at specific requests.