Gluon CloudLink Connectors

One of the features of Gluon CloudLink is to link it with an existing back end infrastructure. The linking between the back end infrastructure and Gluon CloudLink is bidirectional and each direction can be split up in two different parts:

push: data is updated in one end and sent through to the other side
pull: data is requested by one end by asking it from the other side

A Gluon CloudLink Application can enable such a link by activating and configuring a Connector. Different connector implementations are provided by Gluon CloudLink out of the box, but not all of them do necessarily implement both push and pull in both ways. And depending on the configured Connector, some extra code will be required on the back end application as well. E.g. when linking to Gluon CloudLink with the REST Connector, a handler must exist on the back end application that listens for HTTP callbacks that are requested by Gluon CloudLink.

Activating and configuring a Connector for a Gluon CloudLink Application is done in the Gluon CloudLink Dashboard, which we will simply refer to as the Dashboard from here on.

We will now discuss the different connector implementations in more detail below.

1. REST Connector

The REST Connector sends and receives data over an internet connection using the standard HTTP protocol. The Connector implements both push and pull in both directions.

1.1. Gluon CloudLink → Back End Infrastructure

When using the REST Connector to link to a back end system, the Gluon CloudLink Application only needs to be configured with the URL where the requests from Gluon CloudLink will be sent to.

gluon cloudlink dashboard rest connector

1.1.1. Push endpoints

When a client application requests data to be added, updated or removed from Gluon CloudLink, those requests will be mapped with the REST Controller by making an HTTP request to one of the following six endpoints. Each of them should be implemented on the back end application to be able to handle the request.

Object Methods

Table 1. A new object is added
Description	A new object is added to Gluon CloudLink. The `objectIdentifier` is the identifier that is passed in from the application client when retrieving or storing the object.
URL	/object/{objectIdentifier}/add
Method	POST
Request Body	JSON payload of the new object

Table 2. An existing object is updated
Description	An existing object is updated in Gluon CloudLink. The `objectIdentifier` is the identifier that is passed in from the application client when retrieving or storing the object.
URL	/object/{objectIdentifier}/update
Method	POST
Request Body	JSON payload of the updated object

Table 3. An existing object is removed
Description	An existing object is removed from Gluon CloudLink. The `objectIdentifier` is the identifier that is passed in from the application client when retrieving or storing the object.
URL	/object/{objectIdentifier}/remove
Method	POST
Request Body	The request body is empty

List Methods

Table 4. A new object is added to a list
Description	A new object is added to a list. The `objectIdentifier` is an identifier that is assigned to the object specific to Gluon CloudLink, i.e. the client application is not aware of this identifier. This is in contrast to the `listIdentifier`, which is the identifier that is passed in from the application client when retrieving the list.
URL	/list/{listIdentifier}/add/{objectIdentifier}
Method	POST
Request Body	JSON payload of object that is being added to the list

Table 5. An existing object is updated in a list
Description	An existing object in the list is updated. The `objectIdentifier` is an identifier that is assigned to the object specific to Gluon CloudLink, i.e. the client application is not aware of this identifier. This is in contrast to the `listIdentifier`, which is the identifier that is passed in from the application client when retrieving the list.
URL	/list/{listIdentifier}/update/{objectIdentifier}
Method	POST
Request Body	JSON payload of object that is being updated in the list

Table 6. An existing object is removed from a list
Description	An existing object is removed from a list. The `objectIdentifier` is an identifier that is assigned to the object specific to Gluon CloudLink, i.e. the client application is not aware of this identifier. This is in contrast to the `listIdentifier`, which is the identifier that is passed in from the application client when retrieving the list.
URL	/list/{listIdentifier}/remove/{objectIdentifier}
Method	POST
Request Body	The request body is empty

1.1.2. Pull endpoints

When a client application requests an object or a list that is not yet known inside Gluon CloudLink, Gluon CloudLink calls one of the following two endpoints on the back end application to retrieve the initial object or list information.

Table 7. An object is requested
Description	A new object is being requested from the client application with the specified `objectIdentifier`.
URL	/object/{objectIdentifier}
Method	GET
Response Body	JSON payload of the object to retrieve

Table 8. A list is requested
Description	A new list is being requested from the client application with the specified `listIdentifier`.
URL	/list/{listIdentifier}
Method	GET
Response Body	JSON payload of the list to retrieve. The payload is a JSON array containing a list of zero or more JSON objects. Each JSON object has two keys: `id` that defines the object identifier and `payload` which is a JSON payload of the object, represented as a JSON string.

1.2. Back End Infrastructure → Gluon CloudLink

The back end infrastructure is also able to use the REST Controller to request or update data that is located in Gluon CloudLink. The available endpoints are exactly the same as the ones we described above for the reverse direction, for both the push and pull endpoints. The following URL must be used as the base for each endpoint:

http://cloud.gluonhq.com/2/enterprise

For instance, retrieving a list with the name notes will use the following URL in a HTTP GET request: http://cloud.gluonhq.com/2/enterprise/list/notes

1.2.1. Authorization

Each request you make to the Gluon CloudLink REST Controller endpoint must be signed as an OAuth1 request, by using the credentials of the Gluon CloudLink Application for the consumer key and secret. The HMAC-SHA1 signature is the only supported signature for signing the requests. Read the Signing Requests section on the OAuth1 specification website for more information.

2. Couchbase Connector

The Couchbase Connector is able to send data to an existing Couchbase Server. The only requirement on the Couchbase Server is an existing bucket that will hold the lists and/or objects from Gluon CloudLink.

Currently, only the direction from Gluon CloudLink to a Couchbase Server is available, supporting both pushing to and pulling from the bucket. When activating the Couchbase Connector inside the Dashboard, you will need to provide the following information to let Gluon CloudLink be able to setup a connection with the Couchbase Server:

Nodes: a list of nodes that the Couchbase Client on Gluon CloudLink uses to setup the connection to a Couchbase Cluster. You can specify more than one node, by separating them with a semicolon.
Bucket Name: the name of the Couchbase bucket that will hold the lists and/or objects
Bucket Password: the password of that Couchbase bucket

gluon cloudlink dashboard couchbase connector

2.1. Pushing Data

2.1.1. Objects

Objects are stored in the Couchbase bucket using a key named objects/{objectIdentifier}, where objectIdentifier is the identifier that is passed in by the client application when storing or retrieving the object.

The document itself will be a JSON document that represents the JSON payload of the object. An example of such an object can be seen below:

objects/notes-settings

{
  "fontSize": 10,
  "sortingId": 2,
  "ascending": true,
  "showDate": false
}

2.1.2. Lists

Lists are also stored as a document with a key named lists/{listIdentifier}, where listIdentifier is the identifier that is passed in by the client application when retrieving the list.

For each object in the list, the document will contain a key that matches the identifier of the object. The value that is mapped to that key is a JSON document that represents the JSON payload of the object. Below is an example of a list that contains two objects:

lists/notes

{
  "af52f4c6-a64b-4823-b9fb-3cbef79d7577": {
    "creationDate": 1463062055,
    "title": "new note",
    "text": "sample 2"
  },
  "f880774a-20e9-11e6-b67b-9e71128cae77": {
    "creationDate": 1463054952,
    "title": "another note",
    "text": "and also another sample text"
  }
}

2.2. Pulling Data

Gluon CloudLink can also pull data from the same Couchbase Server when a list and/or object is retrieved that is not yet known within the Gluon CloudLink data store. It will try to retrieve a list or object from the configured bucket, by using the same identifiers as described in the push section above: lists/{listIdentifier} for lists and objects/{objectIdentifier} for objects. The format of the documents stored inside the Couchbase bucket must also follow the same format as described in the previous section.