Kapua REST API

Kapua exposes REST API which can be used to access Kapua data and invoke Kapua operations. REST API application is running as a dedicated Java process.

In order to access the API application running in OpenShift you will first need to find out the proper URL. There are two ways to do that, all following examples will use http://RESTAPIADDRESSS as a placeholder which has to be substituted by the actual URL.

Through the router

OpenShift routes all calls through a front-facing router application. This enables it to load balance and auto-create hostnames. It is the recommended way to access applications.

$ oc status | grep api
http://api-eclipse-kapua.1.2.3.4.xip.io to pod port http (svc/kapua-api)
  dc/kapua-api deploys docker.io/kapua/kapua-api-jetty:latest

The resulting URL would be: http://api-eclipse-kapua.1.2.3.4.xip.io

Direct docker container access

If you have access to the OpenShift master/node where the Kapua REST API is running on you can also directly access the Docker container. The following command will give you the network information of this service:

$ oc get service | grep api
kapua-api       172.30.200.124   <none>        8080/TCP             1d

The resulting URL would be: http://172.30.200.124:8080 but it would only work from the local machine where OpenShift is running.

API documentation

In order to retrieve a list of API operations, you can use Swagger UI available the following URL - http://RESTAPIADDRESSS/doc.

Depending on your OpenShift configuration, those hostnames might be created differently. The "xip.io" domain is a DNS system which simply resolved to the IP address provided in the hostname.

Documentation on Kapua Web Site

REST API Documentation is also available at Eclipse Kapua Web Site

Logging into Kapua REST API

Before you start to work with REST API, you need to authenticate yourself and receive session token which you will then pass together with every subsequent invocation of REST API. The easiest way to receive token is by using Swagger UI which will generate CURL command for you:

http://RESTAPIADDRESSS/doc/#!/Authentication/loginUsernamePassword

The following examples assume you are setting the environment variable APIURL with the URL of the API, like:

APIURL=http://api-eclipse-kapua.1.2.3.4.xip.io

You can use default Kapua admin username/password pair i.e. kapua-sys/kapua-password. This is the CURL request command generated by Swagger UI:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "password": [
    "kapua-password"
  ],
  "username": "kapua-sys"
}' "${APIURL}/v1/authentication/user"

The CURL command above should generate response similar to the snippet below:

{
  "type": "accessToken",
  "id": "l5_1yIHD3Ao",
  "scopeId": "AQ",
  "createdOn": "2017-03-27T17:00:37.22Z",
  "createdBy": "AQ",
  "modifiedOn": "2017-03-27T17:00:37.22Z",
  "modifiedBy": "AQ",
  "optlock": 1,
  "tokenId": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL3d3dy5lY2xpcHNlLm9yZy9rYXB1YSIsImlhdCI6MTQ5MDYyNjgzNywiZXhwIjoxNDkwNjI4NjM3LCJzdWIiOiJBUSIsInNJZCI6IkFRIn0.koYBckEw84Mfe-zgfJ7LOcWSGdMiK0bhYoNNYWJNY8e7qdA4cbFwxpivr64sS6xVXY-M7KvACwCVjmnrImUITSKLL1i76cnZAVb9wIoi1fQy3DcYBFJ-4YNdDqrLtzTUTbroqIN6p9NIszl2coV4Ev-jaFGb_5Bl8hmhSktlHTVZTBw4w5iLG_nQhUm_ShOAeeaUiJ_2dYG0l6xngKzyRKMhoUIPK6msolG0PZSvsTct1pR8CQY-BytiVOE8EP-uSJmvn96PMXuquSrrOV1Mg82EoMgWjWC6wxUdeE0nZi0epHTVKfgmQzeZhlWtcyz5BG9Rr3E3jmh6RlKRTcHGZg",
  "userId": "AQ",
  "expiresOn": "2017-03-27T17:30:37.108Z",
  "refreshToken": "4d97e180-4665-4fb5-be32-c8fa88711606",
  "refreshExpiresOn": "2017-03-27T22:00:37.108Z"
}

The token itself is located under tokenId key. You can use your token by adding Authorization: Bearer YOUR_TOKEN HTTP header to the API call. For example the snippet below uses retrieved token to list users available for current tenant:

The following examples assume that you set the API token in the environment variable TOKEN like:

TOKEN='eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL3d3dy5lY2xpcHNlLm9yZy9rYXB1YSIsImlhdCI6MTQ5MDM2Nzc0MCwiZXhwIjoxNDkwMzY5NTQwLCJzdWIiOiJBUSIsInNJZCI6IkFRIn0.HA3cgNUPK3LJbziP7ZVjke8dLS5xVKj3RuhjFPoJYUNVyo7MxH-1Wiuls7X4LV-PZWjR_Y3wjuwiVopED22FGNUc_fzXhZIb69Ifod6lE0lTCYABDMc7RwQOEdqTlqUv2NiprZ3-VAMYYlvjEJQD_s2EN2vyikXCPXc9MIU8pDVKOwhu1EjZC9X7vTUyMnwbNcoAKp0uI5-rdDuyTZDoS6r82gp69wJ5HIwxa8r1MZxbmTCP-HaaZ29J7YfI-RYGoVzbUOsOQV725xUKhzVJEhtyFlt38-Xuevac6JayyErd06lWR1wLgHwjAQWLuy-G2tuq10lEzj3GuDhnyIihlg'


curl -X GET --header "Authorization: Bearer ${TOKEN}" --header "Accept: application/json" "${APIURL}/v1/_/users?offset=0&limit=50"
{"type":"userListResult","limitExceeded":false,"size":2,"items":{"item":[{"type":"user","id":"Ag","scopeId":"AQ","createdOn":"2017-03-24T14:48:03.686Z","createdBy":"AQ","modifiedOn":"2017-03-24T14:48:03.686Z","modifiedBy":"AQ","optlock":0,"name":"kapua-broker","status":"ENABLED","displayName":"Kapua Broker","email":"kapua-broker@eclipse.org","phoneNumber":"+1 555 123 4567","userType":"INTERNAL"},{"type":"user","id":"AQ","scopeId":"AQ","createdOn":"2017-03-24T14:48:03.686Z","createdBy":"AQ","modifiedOn":"2017-03-24T14:48:03.686Z","modifiedBy":"AQ","optlock":0,"name":"kapua-sys","status":"ENABLED","displayName":"Kapua Sysadmin","email":"kapua-sys@eclipse.org","phoneNumber":"+1 555 123 4567","userType":"INTERNAL"}]}}