Request Basics

In this section, we will be taking a look at request features that are common to the various request categories such as SMSRequest, VoiceRequest, BalanceRequest, etc. Subsequent discussions will dissect other aspects of requests that are specific to each request category.

Importing Modules / Namespaces

To simplify the use of classes defined in the SDK, it is recommended to important the required modules or namespaces in applications. This enables developers to use classes without preceding them with their namespaces.

Common modules that may be imported are shown as follows.

  using Zenoph.Notify.Enums;
  using Zenoph.Notify.Request;
  using Zenoph.Notify.Response;

The above statements import common modules that will be needed to send messages. There are however other modules that can be imported when needed. These include modules for VoiceRequest, MessageDeliveryRequest, CreditBalanceRequest, CreditBalanceResponse, etc.

Initialising Requests

Before a request can be submitted, a Request object must be created and its required properties set before submitting the request for processing.

The following sample code shows initialisation of SMSRequest object that can be used for sending SMS after setting required properties.

// create request object
SMSRequest request = new SMSRequest();

Request Host URL

To submit request data for procesing, the server application needs to be specified as the host parameter. The request host is the top level domain on which the messaging account was created preceded by api.. That is, the host domain needs to be set as api.smsonlinegh.com.

To set the application host domain, a call to the method setHost() of the request object must be made by passing the host domain as argument to the call.

  // create request object 
  SMSRequest request = new SMSRequest();
	
  // set host
  request.setHost("api.smsonlinegh.com");

Any request to be made, such as SMSRequest, VoiceRequest, CreditBalanceRequest, etc., must explicitly set the host domain by calling setHost() before submitting the request to the server.

Authentication

Every request to the server must be accompanied by authentication parameters to prove the authenticity of the request. There are two authentication mechanisms available from which one must be specified to indicate how authentication will be performed. We refer to these as authentication models.

Authentication Models

Authentication models indicate which authentication parameters are being supplied to be used in authenticating the request. One of two authentication models can be specified. Either API Key or account username and password can be specified for verifying request account.

Auth Model Description
PORTAL_PASS Indicates that authentication will be done with account username and password
API_KEY Indicates that authentication will be done with API Key generated in user account

API Key Authentication

API Key Authentication requires setting an API Key for authentication. If not already available, it must be generated in API configuration of user account settings. Setting API Key for authentication is highly recommended since it avoids using account credentials in external applications. For App Integrated accounts, only API Key authentication is allowed.

To use API Key for authentication, the authentication model must be set as API_KEY with a call to setAuthModel() and then setting the API Key with a call to setAuthApiKey().

Using an object of SMSRequest as an example, we can set the API Key for authentication as demonstrated below:

  // set API key for authentication
  request.setAuthModel(AuthModel.API_KEY);
  request.setAuthApiKey("d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128");

Authentication model must be set before setting the API Key with a call to setAuthApiKey().

Portal Pass Authentication

With Portal Pass authentication, a client's account login and password are set to be used for request authentication. This authentication mechanism is not recommended since it can reveal the login credentials of an account especially where authentication parameters are stored in external files.

To use this authentication mechanism, a call to setAuthModel() must be supplied with PORTAL_PASS as the authentication model. Once set, a call to setAuthLogin() and setAuthPassword() methods respectively will set the account login and password for request authentication.

  // set API key authentication
  request.setAuthModel(AuthModel.PORTAL_PASS);
  request.setAuthLogin("account_login");
  request.setAuthPassword("password");

As with API Key authentication, authentication model must be set before calling setAuthLogin() and setAuthPassword() to set the account login and password respectively. In this case, it must be set to PORTAL_PASS before calling setAuthLogin() and setAuthPassword() methods.

Warning

Using account login and password for API authentication in applications is not recommended as it may reveal account credentials for accessing the client's portal account. It is highly recommended to use API_KEY for authentication with API calls.

Securing Requests

By default, all requests are sent through a secured HTTPS connection. Sending requests with secured connection is highly recommended. However, requests can also be sent through unsecured HTTP connection. Sending requests through HTTP is however not recommended. It may temporarily be used where in rare cases, there is a challenge with secure connection, when the client application is not able to submit HTTPS requests, or when testing API integration on local servers. We however highly recommend sending requests with secured HTTPS connection in production environments.

To use HTTPS connection, call the method useSecureConnection() with true value. This is the default and therefore the call with true value may not be needed. However, to use HTTP connection (insecure), call the method with false value.

  // use secure connection
  request.useSecureConnection(false);
Warning

Using HTTP connection is insecure since it may lead to data leak. It is recommended to use HTTPS connection for all requests.

If the call to useSecureConnection() with true value fails, try to set it to false. If this works, then the system on which the application is running uses unsupported connection certificate. On some systems, the application can set a higher certificate for connection. For instance, in Microsoft .NET applications, the ServicePointManager can be used to set the certificate to TLS1.2 or higher. If this cannot be done, then useSecureConnection() should be passed false to ignore secure HTTPS connection.

Request Exception

Before submitting a request, all necessary checks are done on the client side to ensure that required fields for the request have been provided. If there is a missing or invalid field requirement, an Exception will be thrown and the submit request will be aborted. When the request is received on the server, further checks are made to ensure validity of request data. If there is missing or invalid data, RequestException will be thrown.

The distinction between the two Exceptions lies in where the error report originates. If the error is reported from the client side before request is sent to the server, then an Exception is thrown. However, if the error is reported from the server after submitting the request, then RequestException will be thrown.

A RequestException contains additional data that gives more detail regarding the cause of the error. This will be a member of the RequestHandshake enumeration. To obtain this handshake indicator to know the cause of the Exception, getRequestHandshake() must be called on an object of RequestException.

To handle Exceptions, applications must catch both Exception and RequestException. Alternatively, applications can catch only Exception and check if the object is of RequestException class.

try {
    // Initialise SMS request
    SMSRequest request = new SMSRequest();
	
	// set request host and authentication properties
    request.setHost("api.smsonlinegh.com");
    request.setAuthModel(AuthModel.API_KEY);
    request.setAuthApiKey("d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128");
	  
    // set message properties and submit
    request.setMessage("A test SMS");
    request.setSender("TEST");
    request.addDestination("233241111111");
    request.submit();
}
  
catch (RequestException ex){
    // get the handshake indicator to know the cause of the error
    RequestHandshake handshake = ex.getRequestHandshake();
	  
    // Exception catch code continues
}
  
catch (Exception ex){
    // Exception catch code continues
}

Notice that in VB/VBA, we only handle the general error by outputting the error description.

An alternative approach to use only a single catch block will be to catch the general Exception and check if the Exception object is of the type RequestException. If the object is of RequestException, then it should be cast in order to call getRequestHandshake() method for the RequestHandshake indicator. This will give more information about the cause of the error.

try {
    // Initialise SMS request
    SMSRequest request = new SMSRequest();
	  
    // set request host and authentication properties
    request.setHost("api.smsonlinegh.com");
    request.setAuthModel(AuthModel.API_KEY);
    request.setAuthApiKey("d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128");
	  
    // set message properties and submit
    request.setMessage("A test SMS");
    request.setSender("TEST");
    request.addDestination("233241111111");
    request.submit();
}
  
catch (Exception ex){
    if (ex is RequestException){
	    RequestHandshake handshake = ((RequestException)ex).getRequestHandshake();
    }
	  
    // Exception catch code continues
}

It is important to ensure that the namespaces for RequestException and RequestHandshake as well as all other type names have been imported into the project to be able to use their unqualified names.