Request Basics

In this section, we will be looking at basic structure and formats for sending requests as well as basic look at responses that are returned. Subsequent discussions will build on the basic knowledge in this section for more seamless messaging and response processing.

Request Header

In sending requests for processing, the request header must be properly set in order for the server to understand and read the request data. Three important request header properties that must be set are Content-Type, Accept, and Authorization headers.

Our REST API accepts request data in either JSON or XML data format. The content type must therefore be set to either application/json or application/xml depending on the format of the request data. Similarly, applications making the request must also indicate the content type in which the response should be returned. The Accept property of the request header can therefore be set to either application/json or application/xml. In later discussions, we will see other content type specifiers that can be set for Content-Type and Accept headers.

To pass request authentication, applications must also set authentication parameters in the Authorization header. We will take a look at how to do this shortly.

Content-Type: application/json
Accept: application/json
Host: api.smsonlinegh.com 
Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128

Request URL

The request resource is indicated as part of the URL that a request is submitted to for processing. Generally, it consists of the host domain, API version, request resource, etc. For example,

https://api.smsonlinegh.com/v5/message/sms/send

In the sections that follow, request URLs will follow this pattern. As will be observed later, the difference in the request URLs depends on the actual resource that is being accessed for request processing. That is, the format will generally look like the following:

https://api.smsonlinegh.com/v5/[request_resource]

Thus, https://api.smsonlinegh.com/v4 will always be the same with the request resource as an appendix. In this case, v5 is the version of the API being accessed. A typical example is the request URL for checking credit balance.

https://api.smsonlinegh.com/v5/report/balance

Request Authentication

All requests to the messaging server are checked for authenticity of the requests. To pass validation, request credentials must be set in the request header.

There are two authentication mechanisms from which one can be specified for verification. We refer to these as Authentication Models.

Authentication Model

The authentication model indicates which authentication parameters have been set to be used in authenticating the request.

When using API Key authentication, the Authorization header must be set to key followed by the generated account API Key.

With Portal Pass authentication, the Authorization header must be set to factor followed by the base64 encoded string of the account login and password joined together by the character sequence __::. We will see an example shortly under Portal Pass Authentication.

API Key Authentication

API Key authentication involves setting an API Key to be used in request authentication. If not already generated, the API Key must be generated in API configuration from client account settings.

With API Key authentication, the authentication model must be specified as key followed by the generated API Key for authentication. The resulting value must be set as the value for the Authorization header.

Content-Type: application/json
Accept: application/json
Host: api.smsonlinegh.com 
Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128

As can be seen, the Authorization header has been set by specifying the authentication model as key followed by the API Key as key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128.

Setting API Key for authentication is highly recommended since it avoids exposing account username and password in external applications. For App Integrated accounts, only API Key authentication is permitted.

Note

It is highly recommended to use API Key for authenticating requests in order to avoids exposing portal username and password in applications.

Portal Pass Authentication

With Portal Pass authentication, a client account username and password is set to be used in authenticating requests through the API. This authentication mechanism is not recommended since it exposes account credentials in external applications.

To specify the use of this authentication mechanism, authentication model must be specified as factor. Authentication factor must then be generated as base64 encoded string from account username and password joined together with the characters __::.

For example, if the account username is account_login and the password is account_password, then they must be joined together as account_login__::account_password. The resulting string after the join must be encoded to base64 string and set as the value for the request Authorization header as factor.

Content-Type: application/json
Accept: application/json
Host: api.smsonlinegh.com 
Authorization: factor YWNjb3VudF9sb2dpbl9fOjphY2NvdW50X3Bhc3N3b3Jk

Warning

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

Request Data

For requests that require initial data for processing, the request data must be provided as request body. Some requests do not require initial data to be submitted and in such cases, no request data will be submitted For example, when checking credit balance, no additional data is required in addition to the authentication parameters.

Securing Requests

To ensure the security of requests, it is highly recommended that all requests be submitted through a secured HTTPS connection (HTTPS). For example,

https://api.smsonlinegh.com/v5/report/balance

The above request URL uses https as the protocol to request account credit balance.

Besides https, applications can also submit requests using the http protocol. This is however not encouraged. For some applications, it may be convenient to submit requests with http protocol when testing integration on local servers. It may also be used when the operating system on which the application is running has an unsupported or lower TLS version installed.

http://api.smsonlinegh.com/v5/report/balance

Warning

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

A Test Request

To summarise our discussion on the basics of requests, we will examine a sample request that checks an account credit balance. Once the request succeeds, then you will be ready for messaging.

To get the credit balance, we will make a POST request to the balance request URL whiles specifying Accept, Host, and Authorization headers. In this case, we indicate that we want to be served with a JSON response.

POST https://api.smsonlinegh.com/v5/account/balance
  
Content-Type: application/json
Accept: application/json
Host: api.smsonlinegh.com 
Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128

In this request for credit balance, no data will be prepared for the request body. The only requirement is the account API key which is expected to be set as request header item as Authorization. Sample application code is shown below:

<?php
// API endpoint for the request.
// If [https] is not supported when testing,
// then change the request protocol to [http]
$endPoint = 'https://api.smsonlinegh.com/v5/account/balance';

// set up the request headers
$headers = [
    'Host: api.smsonlinegh.com',
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
];

$ch = curl_init($endPoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute for response
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// close curl
curl_close($ch);

if ($httpCode == 200){
    var_dump($response);
}

# API host domain
host = 'api.smsonlinegh.com'

# API request URL
requestURL = 'http://api.smsonlinegh.com/v5/account/balance'

# set up the request headers
headers = dict()
headers['Host'] = host
headers['Content-Type'] = 'application/json'
headers['Accept'] = 'application/json'
headers['Authorization'] = 'key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'

httpConn = httpClient.HTTPConnection(host)
httpConn.request('POST', endPoint, None, headers)

# get the reponse
response = httpConn.getresponse()

if response.status == 200:
    print(response.read())
else:
    print('Request was unsuccessful')

const axios = require('axios');

let endPoint = `http://api.smsonlinegh.com/v5/account/balance`;

// set up the request headers
let headers = {
    'Host': 'api.smsonlinegh.com',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
};

// request for account balance
axios.request({
    url: endPoint,
    method: 'post',
    headers: headers
})
.then(function(response){
    // the http status code
    let httpStatus = response.status;
		
    if (httpStatus == 200){
        let responseData = response.data;
        console.log(responseData);
    }
})
.catch(function(error){
    console.log(error);
});

When the above code is executed, the response will contain data similar to the response data below:

JSON
XML

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

<response>
    <handshake>
        <id>0
        <label>HSHK_OK</label>
    </handshake
    <data>
        <balance>9842</balance>
        <model>quantity</model>
        <currencyName>null</currencyName>
        <currencyCode>null</currencyCode>
    </data>
</response>

The response data that is returned after each request will depend on the actual request that was made. However, the response data is based on a common structure. The next section on Response Basics covers this basic structure of all responses that are returned.