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"}]}}