Kapua REST API

Kapua提供访问数据和调用操作的REST API。REST API应用由专用Java进程运行。

在访问运行在OpenShift中的API前，可以通过以下两种方式找到格式为http://RESTAPIADDRESSS的URL地址。

通过路由功能

OpenShift通过前置路由程序提供路由功能，支持负载平衡和自有规则主机名。推荐使用此方式访问应用。

$ 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

生成URL为：http://api-eclipse-kapua.1.2.3.4.xip.io

直接访问Docker容器

在运行Kapua REST API的电脑上，如果能访问OpenShift主站/从站，也可以直接访问Docker容器。使用如下命令可以获得服务网络信息：

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

生成URL为：http://172.30.200.124:8080 注意只能在运行OpenShift的本机使用。

API 文档

使用Swagger界面检索API，URL地址为：http://RESTAPIADDRESSS/doc。

主机名依照OpenShift配置而不同。域名"xip.io"简单指向主机IP地址。

登陆到Kapua REST API

在使用REST API前，需要认证并获取会话token。最简单的方式是使用Swagger界面生成CURL命令：

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

以下示例假设设置环境变量APIURL如下：

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

可以使用默认Kapua管理员用户名和密码例如kapua-sys/kapua-password。Swagger界面生成CURL请求命令如下：

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

响应片段如下：

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

token值位于字段tokenId下。通过在API调用的HTTP头信息中添加Authorization: Bearer YOUR_TOKEN 使用token。例如如下用户列表请求片断：

以下示例假设TOKEN为：

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":"[email protected]","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":"[email protected]","phoneNumber":"+1 555 123 4567","userType":"INTERNAL"}]}}