Introduction

The purpose of this article is to explain the concepts and theory of REST API support in CloudIO Platform. The guide is prepared to enable integration developers to understand and use the REST API features available within CloudIO Platform. The guide demonstrates the steps involved in exposing data via. REST API along with the steps involved in consuming those APIs that are exposed within CloudIO Platform.

What is REST?

REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol and in virtually all cases, the HTTP protocol is used.

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to communicate between different applications, simple HTTP is used to make calls.

In many ways, the World Wide Web itself, based on HTTP, can be viewed as an REST-based architecture. RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.

REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL, et al.). Despite being simple, REST is fully-featured; there's basically nothing you can do in Web Services that can't be done with a RESTful architecture.

REST is not a "standard". There will never be a W3C recommendation for REST, for example. And while there are REST programming frameworks, working with REST is so simple that you can often "roll your own" with standard library features in languages like Java, Perl or C.

CloudIO Platforms REST Services are built using Java around the same Data Sources that are used by the user interface layer. That way you can reuse all your existing business logic defined at the DataSource layer between the User Interface & REST Web Services Clients.

REST API Use Cases

CloudIO Platform can pull & push data from any JDBC2 compliant databases natively via JDBC calls. Hence, if you are trying to build a user interface using CloudIO Platform against your existing database, you can connect the Platform directly to the database natively using JDBC. Having said that you may have some use cases where you may not have direct access to the database or you would like to integrate a system that's not under your control.

CloudIO REST APIs can be used for the following use cases

  1. E-Commence Web Integration e.g. Magento
  2. Native Mobile Application Development e.g. iOS or Android
  3. 3rd Party or Legacy System Integration e.g. 3PLs

Understanding CloudIO REST APIs

A REST resource in CloudIO is a piece of information, such as a single data record, a collection of records. Each resource in the CloudIO REST API is identified by a named URI and is accessed using standard HTTP POST method. The resource is used to interact with any DataSource within CloudIO Platform.

For example, you can:

  1. Obtain detailed information about any CloudIO DataSource such as RaUsers or RaRoles
  2. Obtain detailed information about any application specific DataSource
  3. Perform a search on any DataSource
  4. Insert, Update or Delete records

Suppose you want to retrieve a row from RaUsers with userName ADMIN:


Important characteristics of the CloudIO REST API resources and architecture are as follows 

Stateless

Each and every request from the client to server must contain all the information necessary to understand the request along with the sessionId.

Caching

Since all the REST APIs are executed, via. DataSource, real-time against a Database, the results are not cacheable

HTTP

All REST APIs are accessed over HTTP protocol.

URI

All REST APIs are named using a base URI that follows your CloudIO URI. e.g. https://host:port/api/Datasource[/operation] where operation is one of the following values

insert, update, delete, post or query (Default)

Authentication

CloudIO REST API supports authentication using username/password or with a key & secret or with OAuth 2.0 (an open protocol to allow secure API authorization).

JSON

Both the request and response payload are in the JavaScript Object Notation (JSON) format with UTF-8 encoding. Date-time information is in ISO 8601 format e.g. 2012-08-30T02:56:20.000-0700

Understanding Authentication

CloudIO uses the OAuth protocol to allow users of applications to securely access data without having to reveal username and password credentials. For a simple integration, CloudIO also supports username/password or with a key & secret option.

Before making REST API calls, the client application must authenticate the application user using one of the above methods.

After successfully authenticating the client app user with CloudIO, the client will receive a sessionId token which can be used to make authenticated REST API calls.

To generate a token and secret key, navigate to /api/keys using a browser after signing into CloudIO Platform

A sample sign-in request with a key and secret and its respective response is shown below

The sessionId attribute in the response must be stored by the client application and must be passed in all the subsequent authenticated REST API calls. The sessionId will expire if the client app is inactive for the number of minutes specified in the sessionTimeout attribute. e.g. 60 minutes in the above example. You can set the sessionTimeout for the REST Client user using Default Session Timeout CloudIO profile option at the user level.

Note: the client application will only have access to the DataSources that are assigned to the Roles accessible to the connected user

Checking the Validity of an Existing Session

The sessionId passed in every REST API request must be valid and active. You can use validateSession API to validate a given sessionId before making the actual REST API request.

Error Handling

It's possible a REST API request may result in an error. Always check for error or _error in the response and if the value is Y then the API has resulted in an error. Check for errorTitle & errorMessage for the reason for the failure. If the failure is due to the expired sessionId passed, then sessionExpired will be set to Y. For debug purposes, you can check sqlCall for the SQL that caused the exception and dataSource for the DataSource that caused it. If the client user is an Administrator, then an additional attribute adminMsg would be populated with a more detailed error message.

Performing a Query Operation

A query or search operations can be used to fetch data out of CloudIO Platform. The following are the parameter attributes that can be passed with the request payload

Special characters in attribute name and values

The name-value pairs specified as part of the data JSON Object may use the following special characters to perform a complex search

A sample request and response is shown below

Performing an Insert Operation

Using the Insert operation, the client application can insert one or more rows. The payload used in the JSON POST is of JSON Array of Objects type with name value pairs, where the name should match the DataSource attribute name but in camel case format. e.g. Customer Name attribute should be named as customerName for the key in the JSON Object.

The URI to perform the insert operation is /api/Datasource/insert

Sample JSON Payload for an Insert Operation

[
  "accountNumber": "345354",
  "address1": "100 Main St",
  "creationDate": "2015-10-28T01:42:30.789Z",
  "createdBy": 1,
  "lastUpdateDate": "2015-10-28T01:42:46.964Z",
  "lastUpdatedBy": 1,
  "partyName": "CloudIO Inc."
,
  "accountNumber": "345355",
  "address1": "333 Main St",
  "creationDate": "2015-10-28T01:42:30.789Z",
  "createdBy": 1,
  "lastUpdateDate": "2015-10-28T01:42:46.964Z",
  "lastUpdatedBy": 1,
  "partyName": "CloudIO India Pvt. Ltd.
]
Note!

Make sure to populate all the attributes that are marked mandatory at the Datasource level.

Performing an Update Operation

Using the Update operation, the client application can update one or more rows. The payload used in the JSON POST is of JSON Array of Objects type. All the primary key attributes must have a value and only the passed attributes will be updated.

The URI to perform the update operation is /api/DataSource/update

Performing a Delete Operation

Using the Delete operation, the client application can delete one or more records from the DB. The payload used in the JSON POST is of JSON Array of Objects type. Only the primary key attributes are required for the delete operation.

The URI to perform a delete operation is /api/DataSource/delete

CloudIO REST API Playground

CloudIO Platform offers two REST API Playgrounds for the Developers to try out the REST API calls. The first API Playground can be accessed via a URI /api for making guided REST API calls. It offers a simple UI for the Developer to select a data source and enter the parameter values for performing the REST API calls. The system would automatically generate the REST payload in real-time and displayed on the right side area for reference purposes.

The second API Playground can be accessed via a URI / jsontest for testing the APIs with a given REST payload. It also offers a simple solution for load testing the REST APIs. The load test results will be shown in a graph as shown below.