Understanding our Open API Basics

REST stands for “Representational State Transfer” and defines an architecture style that describes a set of rules that should be followed when creating or fetching resources using a URL. A resource is an object or representation of data that needs to be sent to or received from a server. URL (Uniform Resource Locator) is a path through which a resource can be located and some actions can be performed on it. An application programming interface (API) that follows REST standards is called a RESTful API. For the most part, RAKBANK Open APIs are RESTful.

Open API Request

RAKBANK Open API requests are made up of the following:

• API URL
• HTTP Method
• API Security
• Request Parameters

API URL

The API URL is defined by the endpoint, basepath and path of the API as shown below.

API Endpoint

API Endpoint is the starting point of the API URL that changes based on the environment. Please ensure the API endpoints are stored as configurable values in your application for ease of movement between environments. For information about the different environments available for our Open APIs and their corresponding API endpoints, see Environments.

API Basepath

API Basepath is the URL prefix for all API paths and typically has the version no. of the API product.

API Path

API Path is the rest of the API URL after the API basepath. This is different for each of our Open APIs and will be provided in the API docs along with the supported HTTP methods for the path.

A path may represent a collection resource or a single instance resource. For example, we can identify “customers” collection resource using the endpoint “/customers”. We can identify an instance “customer” resource using the endpoint “/customers/{customer_id}”.
For e.g.
POST /customers
GET /customers/1234567

HTTP Method

RAKBANK Open APIs support the following HTTP methods to manipulate resources:

• POST creates a resource without passing an id or performs custom actions like partial update.
• GET returns a representation of a resource.
• PUT creates or replaces a resource with an id.
• DELETE deletes the resource.

The following table shows how the RAKBANK Open APIs use HTTP methods on resources.

** Hybrid REST
In scenarios where the GET URL is very long due to numerous filtering parameters, POST might be used instead of GET with “/query” mentioned in the path. All the filtering parameters would be passed in the JSON request to the POST URL.
E.g. /v2/fx_rates/query

API Security

RAKBANK Open APIs are protected by various API security policies. However, not all policies are turned on in the Sandbox environment. For information about all the different security policies that are applicable in each of our environments, see API Security.

In general, OAuth & API key are applicable for most of the RAKBANK Open APIs. OAuth 2.0 is the industry-standard protocol for authorization. When you register an application, the application is assigned a unique client ID and client secret. These are known as API keys. You must use the client ID when you call an API that requires you to identify your application by using a client ID. In some cases, where OAuth does not apply, both the API keys i.e. the client ID and the client secret will be expected to be passed by the client, in the HTTP header.

The Security section in the API docs of every API, provide the details of the security definitions that are applicable for the API. Where OAuth is applicable, the supported OAuth API endpoint, grant type and scope would also be provided. The client will need to invoke the OAuth API and generate an access token. A valid access token should be then passed in the Authorization header as “Bearer ” while invoking the API.

Note: Since this portal represents the Open APIs available in the Sandbox environment, the API security only applicable for the sandbox would be provided in the Security section of the API Docs. For information on the API security policies applicable to each of the environments available for RAKBANK’s Open APIs, see API Security.

Request Parameters

The RAKBANK Open APIs require a set of parameters to be passed in the request. The parameter may need to be passed in the HTTP header, path, query or body. Some parameters are mandatory and will be marked as Required in the API docs.

The body parameter is mandatory for POST and PUT methods and would represent the resource being created or updated on the server. Some fields in the resource definition may be marked as read only fields. When these are passed in the request, the POST & PUT operation ignore the values of such fields and return the actual representation that is created, to the client, in the response.

Some fields in the request only accept an allowed list of values also known of master data list. For e.g. currency fields expect a valid currency code from the currency code master data list. The API docs of each API has a link to the master data applicable for the API. For information on the complete list of master data applicable for all APIs, see Master Data.

Open API Response

RAKBANK Open APIs use HTTP status codes to let you know the status of your response quickly. In general, the numbers follow the following rules:

• 200+ means the request has succeeded
• 300+ means the request is redirected to another URL
• 400+ means an error that originates from the client has occurred
• 500+ means an error that originates from the server has occurred

The APIs may return any of the following HTTP response codes:

Responses with response code 422 return additional information in the response body in the form of an error structure as outlined below.

A sample error response is provided below.
422 Invalid
{
"status": "422",
"response_code": "422001",
"property": "first_name",
"response_message": "Property missing",
"description": "Invalid object: the property 'first_name' is missing."
}

The API docs has a link to the response codes that are applicable for the API. For information on the complete list of API Response codes, see API Response codes.

In case of success responses, GET operations return the representation of the requested resource. Wherever possible, the POST and PUT operations also return the complete representation of the resource. For e.g. in the below screenshot taken from Partner Beneficiary Management API, the request and the response object for 201 status are both represented by the same “beneficiaries” definition.

In some cases where an existing implementation of a backend API does not return the complete resource, the POST and PUT operation may only return the id or reference id of the resource created. In these cases the 201 or 200 status will return a different object which is not the representation of the resource that was created or updated.