| |
| <!DOCTYPE HTML> |
| <html lang="" > |
| <head> |
| <meta charset="UTF-8"> |
| <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> |
| <title>REST API · Eclipse Kapua™ User Guide</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge" /> |
| <meta name="description" content=""> |
| <meta name="generator" content="GitBook 3.2.2"> |
| |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/style.css"> |
| |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css"> |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css"> |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <meta name="HandheldFriendly" content="true"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"> |
| <meta name="apple-mobile-web-app-capable" content="yes"> |
| <meta name="apple-mobile-web-app-status-bar-style" content="black"> |
| <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png"> |
| <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon"> |
| |
| |
| <link rel="next" href="community.html" /> |
| |
| |
| <link rel="prev" href="./" /> |
| |
| |
| </head> |
| <body> |
| |
| <div class="book"> |
| <div class="book-summary"> |
| |
| |
| <div id="book-search-input" role="search"> |
| <input type="text" placeholder="Type to search" /> |
| </div> |
| |
| |
| <nav role="navigation"> |
| |
| |
| |
| <ul class="summary"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="chapter " data-level="1.1" data-path="./"> |
| |
| <a href="./"> |
| |
| |
| Introduction |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter active" data-level="1.2" data-path="rest.html"> |
| |
| <a href="rest.html"> |
| |
| |
| REST API |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.3" data-path="community.html"> |
| |
| <a href="community.html"> |
| |
| |
| Community |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.4" data-path="simulator.html"> |
| |
| <a href="simulator.html"> |
| |
| |
| Simulator |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.5" data-path="jwt_security.html"> |
| |
| <a href="jwt_security.html"> |
| |
| |
| Setup JWT security |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| |
| |
| |
| <li class="divider"></li> |
| |
| <li> |
| <a href="https://www.gitbook.com" target="blank" class="gitbook-link"> |
| Published with GitBook |
| </a> |
| </li> |
| </ul> |
| |
| |
| </nav> |
| |
| |
| </div> |
| |
| <div class="book-body"> |
| |
| <div class="body-inner"> |
| |
| |
| |
| <div class="book-header" role="navigation"> |
| |
| |
| <!-- Title --> |
| <h1> |
| <i class="fa fa-circle-o-notch fa-spin"></i> |
| <a href="." >REST API</a> |
| </h1> |
| </div> |
| |
| |
| |
| |
| <div class="page-wrapper" tabindex="-1" role="main"> |
| <div class="page-inner"> |
| |
| <div id="book-search-results"> |
| <div class="search-noresults"> |
| |
| <section class="normal markdown-section"> |
| |
| <h1 id="kapua-rest-api">Kapua REST API</h1> |
| <p>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.</p> |
| <p>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 <code>http://RESTAPIADDRESSS</code> |
| as a placeholder which has to be substituted by the actual URL.</p> |
| <p><strong>Through the router</strong></p> |
| <p>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.</p> |
| <pre><code>$ 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 |
| </code></pre><p>The resulting URL would be: <code>http://api-eclipse-kapua.1.2.3.4.xip.io</code></p> |
| <p><strong>Direct docker container access</strong></p> |
| <p>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:</p> |
| <pre><code>$ oc get service | grep api |
| kapua-api 172.30.200.124 <none> 8080/TCP 1d |
| </code></pre><p>The resulting URL would be: <a href="http://172.30.200.124:8080" target="_blank">http://172.30.200.124:8080</a> but it would only work from the local machine where OpenShift is running.</p> |
| <h2 id="api-documentation">API documentation</h2> |
| <p>In order to retrieve a list of API operations, you can use Swagger UI available the following URL - <code>http://RESTAPIADDRESSS/doc</code>.</p> |
| <p>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.</p> |
| <p><img src="images/rest-api.png" alt="REST API page"></p> |
| <h2 id="logging-into-kapua-rest-api">Logging into Kapua REST API</h2> |
| <p>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: </p> |
| <pre><code>http://RESTAPIADDRESSS/doc/#!/Authentication/loginUsernamePassword |
| </code></pre><p>The following examples assume you are setting the environment variable <code>APIURL</code> with the URL of the API, like:</p> |
| <pre><code>APIURL=http://api-eclipse-kapua.1.2.3.4.xip.io |
| </code></pre><p>You can use default Kapua admin username/password pair i.e. <code>kapua-sys/kapua-password</code>. This is the CURL request command generated by Swagger UI:</p> |
| <pre><code>curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ |
| "password": [ |
| "kapua-password" |
| ], |
| "username": "kapua-sys" |
| }' "${APIURL}/v1/authentication/user" |
| </code></pre><p>The CURL command above should generate response similar to the snippet below:</p> |
| <pre><code>{ |
| "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" |
| } |
| </code></pre><p>The token itself is located under <code>tokenId</code> key. You can use your token by adding <code>Authorization: Bearer YOUR_TOKEN</code> HTTP header to the API call. For |
| example the snippet below uses retrieved token to list users available for current tenant:</p> |
| <p>The following examples assume that you set the API token in the environment variable <code>TOKEN</code> like:</p> |
| <pre><code>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"}]}} |
| </code></pre> |
| |
| </section> |
| |
| </div> |
| <div class="search-results"> |
| <div class="has-results"> |
| |
| <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1> |
| <ul class="search-results-list"></ul> |
| |
| </div> |
| <div class="no-results"> |
| |
| <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1> |
| |
| </div> |
| </div> |
| </div> |
| |
| </div> |
| </div> |
| |
| </div> |
| |
| |
| |
| <a href="./" class="navigation navigation-prev " aria-label="Previous page: Introduction"> |
| <i class="fa fa-angle-left"></i> |
| </a> |
| |
| |
| <a href="community.html" class="navigation navigation-next " aria-label="Next page: Community"> |
| <i class="fa fa-angle-right"></i> |
| </a> |
| |
| |
| |
| </div> |
| |
| <script> |
| var gitbook = gitbook || []; |
| gitbook.push(function() { |
| gitbook.page.hasChanged({"page":{"title":"REST API","level":"1.2","depth":1,"next":{"title":"Community","level":"1.3","depth":1,"path":"community.md","ref":"community.md","articles":[]},"previous":{"title":"Introduction","level":"1.1","depth":1,"path":"README.md","ref":"README.md","articles":[]},"dir":"ltr"},"config":{"plugins":[],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"eclipse/kapua","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Eclipse Kapua™ User Guide","links":{"home":"http://eclipse.org/kapua"},"gitbook":"3.x.x","description":"Eclipse Kapua™ User Guide"},"file":{"path":"rest.md","mtime":"2017-07-19T09:02:44.000Z","type":"markdown"},"gitbook":{"version":"3.2.2","time":"2017-07-19T09:21:00.257Z"},"basePath":".","book":{"language":""}}); |
| }); |
| </script> |
| </div> |
| |
| |
| <script src="gitbook/gitbook.js"></script> |
| <script src="gitbook/theme.js"></script> |
| |
| |
| <script src="gitbook/gitbook-plugin-search/search-engine.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-search/search.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-sharing/buttons.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script> |
| |
| |
| |
| </body> |
| </html> |
| |
