Response Basics

All requests to the server have corresponding responses sent back to the applications making the requests. For example, after sending a message, a MessageResponse will be returned. Similarly, a request for credit balance will return a CreditBalanceResponse object. These response objects contain data that describe the status of the request or data values requested.

In subsequent sections, we will be taking a deeper look at each of these response objects.

APIResponse: The Base Response Class

All requests submitted through submit() method call return an object of APIResponse. APIResponse is an abstract base class for all other response classes.

When a request is submitted, the response object which is of APIResponse must be cast to the appropriate response object for the request made where necessary.

  // Initialise SMS request
  SMSRequest request = new SMSRequest();
  request.setHost("api.smsfactory.henapp.net");
  
  // set API key for authentication
  request.setAuthModel(AuthModel.API_KEY);
  request.setAuthApiKey("d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128");
  
  // set message properties
  request.setMessage("A test SMS");
  request.setSender("TEST");
  request.addDestination("233241111111");

  // submit message for response
  MessageResponse response = request.submit() as MessageResponse;

We can take a look at another example that requests for account credit balance:

  // Initialise balance request object
  CreditBalanceRequest request = new CreditBalanceRequest();
  request.setHost("api.smsfactory.henapp.net");
  
  // set API key for authentication
  request.setAuthModel(AuthModel.API_KEY);
  request.setAuthApiKey("d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128");
  
  // submit for balance response
  CreditBalanceResponse response = request.submit() AS CreditBalanceResponse;

As seen in some programming constructs, the return value from submit() is cast to the corresponding response object. This is because all submit() methods have a return data type of APIResponse. We will take a deeper look later into the various response objects when we discuss requests that return them.

HTTP Responses

All responses from the server contain the HTTP Status Code values which indicate the status of the request made. For all successful requests, the HTTP status code will be 200 OK. However, it is possible for some requests to fail. Some failed requests may be due to authentication failures, missing request data values, etc.

To obtain the HTTP status code for any request, a call to getHTTPStatusCode() must be made on a response object. This will indicate the status of the HTTP request.

HTTP status codes do not give reasons for all request status that may be encountered in our messaging experiences. For instance, there should be a way to know which parameter is missing in a request data. A generic HTTP status code does not exist for us in every situation of failed requests. To cater for these, custom request status indicators exist to give more insight into failed requests. We refer to these as Request Handshakes.

Request Handshakes

Request handshakes are request status indicators that give more detail about the status of each request. Once a request is made, the server validates the request data to ensure all valid data are provided. If validated, the server sends HSHK_OK to indicate that the request succeeded. If invalidated, the server sends status indicator other than HSHK_OK.

For instance, if the account making the request is inactive, then HSHK_ERR_ACCT_INACTIVE status indicator will be returned. All custom status indicators can be found in the RequestHandshake enumeration.

Practically, any other status indicator other than HSHK_OK will result in Exception being thrown. This means that all successful requests will have a response with HSHK_OK status indicator.

To programmatically obtain the request handshake for a request, we will need to call getRequestHandshake() on the response object that is returned.