-
Notifications
You must be signed in to change notification settings - Fork 62
API: Overview
Nimbits provides a rich API that adheres to both REST and HAL Standards. This document will help you get started with the v3 REST API.
If you spin up a nimbits server and browse to: http://localhost:8080 you'll be prompted to create a user. The first user you create will be the system admin.
Next, try browsing to the root of the API: http://localhost:8080/service/v3/rest/me
You'll get a 404, but not if you use a browser plugin that lets you add an auth header e.g
Authorization : Basic test@example.com:password
You may also want to install a json plugin to prettify your responses.
Since it's json+HAL the response contains links that allow you to navigate the API.
- Your user account is represented by this url: http://localhost:8080/service/v3/rest/me
- Tokens work the same way as v2, but you can (and should) put them or your password to header of your requests using Basic HTTP authentication: Authorization : Basic test@example.com:password12345
- Everything in nimbits (calcs, points, users, etc) has a unique id which is uuid like: 53c00ca6-c176-4a50-8a67-db63babb6d80. So, you can download the json of any entity by using it's uuid: http://localhost:8080/service/v3/rest/53c00ca6-c176-4a50-8a67-db63babb6d80
- You (in a browser) or your software can navigate your entire nimbits tree and data by starting out at service/v3/rest/me and using the urls in the response to get children, parents and data. The REST API is structured like this: http[s]://[server url]/service/v3/rest/[uuid]/[subset]
- You can create users by posting to the ROOT of the API: http://localhost:8080/service/v3/rest (examples below). The first user posted to a new server install will become the super user of that server. In order to post additional users, you must supply the super user's credentials in the header of the POST request.
- When browsing the API - try using chrome with this plugin: JSONView for Chrome it will make it easy to see your data and navigate the internal links.
- nimbits.io is an open source java library you can use to program against the v3 API. A sample java app that uses it to create points and record data is located here on github.
- The v3 API conforms to REST standards more than the v2 API. Everything in Nimbits is represented by a permanent URL. GET Requests to that URL will contain the JSON representing the Entity as well was self links that contain links to itself, children, data and parent. Contents
The easiest way to get to know the API is to login into the public cloud: http://localhost:8080 and browse to your root user url: http://localhost:8080/service/v3/rest/me remember to use JSONView for Chrome or a similar tool to view json data and so the hyperlinks are viewable.
If you have data points or other entities under your account. The first level of your tree will be shown under the children. Data points will have URLs that can POST and GET data to that point.
In the samples below, we'll show you how to create any kind of entity under you tree, record data either by posting a new snapshot or a series of values http://localhost:8080/service/v3/rest/me
- POST Create System Admin
Running the following curl command against a new server will create the system admin, you can also do this by browsing to the server's home page and registering the first user. Note we are posting to the root of the API and in these example, i'm posting to a nimbits instance running on my network at ip address 192.168.1.11 and port 8080 which is the default.
curl -v -XPOST -H 'Authorization: Basic test@example.com:password1234' -H "Content-type: application/json" -d '{ "emailAddress": "test@example.com", "password": "password1234" }' 'http://192.168.1.11:8080/service/v3/rest'
- POST: Create Users
You can create additional users by posting to the root of the api, but you must use the system admin credentials. Upon creation, users passwords are stored with a forward only encryption and cannot be recovered, only reset.
curl -v -XPOST -H 'Authorization: Basic test@example.com:password1234' -H "Content-type: application/json" -d '{ "emailAddress": "newuser@example.com", "password": "newuser's password" }' 'http://192.168.1.11:8080/service/v3/rest'
- GET: Download User
See UserModel.java for class reference
- Download the JSON data for yourself.
curl -v -XGET -H 'Authorization: Basic test@example.com:password1234' -H "Content-type: application/hal+json" 'http://192.168.1.11:8080/service/v3/rest/me'
- Download the JSON data for another user. You must provide System admin Credentials.
curl -v -XGET -H 'Authorization: Basic test@example.com:password1234' -H "Content-type: application/hal+json" 'http://192.168.1.11:8080/service/v3/rest?email=user@example.com'
- PUT: Update User
A PUT command will update the user. If you download the JSON using the command above, make a change and do this PUT to the root of the API, it will be updated. if you include a password field, the password will be reset. You must post these as the system admin
curl -v -XPUT -H 'Authorization: Basic test@example.com:password1234' -H "Content-type: application/hal+json" 'http://192.168.1.11:8080/service/v3/rest'
-DELETE: Delete a user
Delete any entity by doing a delete command to the api using the uuid of the entity. If you provide admin credentials you can delete a user. Try downloading a user first, then using the uuid feild to do a delet.
curl -X DELETE "http://192.168.1.11:8080/service/v3/rest/1234-3234-dd32ds-ssss33"
Post and Download Data
As shown above, every entity in Nimbits can be represented by the API using the uuid in this format: http://localhost:8080/service/v3/rest/abcd-1234-5678-efgh
The response from the API will be a JSON file with the entity's information and self links that can be navigated to using a browser or in your code - to get child entities, values, snapshots, etc. Deep linking is formated like this: service/v3/rest/abcd-1234-5678-efgh/series for downloading series of data, or service/v3/rest/abcd-1234-5678-efgh/snapshot GET or POST operations for the current (most recent in time) value
Data Related self links are only shown if the Entity is a Data Point, which can contain values.
Values in nimbits are structured like this, with small field for efficient downloads:
{ "d":42.0, "t":1437398729067, "dx":"any text data, json or xml", "st":1, "m":"Meta Data" }
Field Definitions
- d: A decimal number
- t: The timestamp in unix epoch format in milliseconds.
- dx: Data, can be empty or any text data you want
- st: Read Only, set by the system to show the alarm status for this value based on point settings. Defined in AlertType.
- m: Meta Data, which can be used to filter data when downloading values by adding the "mask" parameter to your query string using a regular expressions.
You can download a list of values filtered by a date range. You can also include a mask parameter to further filter results bases on a string value or a regular expression.
- start: Start time in unix epoch ms
- end: end time in unix epoch ms
- mask: optional, a regex string or exact match string to filter values based on meta data contents
GET: Download All Point Data for a user filtered by date range and mask
curl -XGET -H 'Authorization: Basic test@example.com:password1234' 'http://localhost:8080/service/v3/rest/me/series'
If you have the uuid of a user, you can download all of their point data by adding the system admin account in the auth header and calling the api like this:
curl -XGET -H 'Authorization: Basic test@example.com:password1234' 'http://localhost:8080/service/v3/rest/me/series?start=0&end=1437398729067&mask=foobar?start=1437398729000&end=1437398729067&mask=foobar'
- GET: Download All Point Data for a point filtered by date range and mask
curl -XGET -H 'Authorization: Basic test@example.com:password1234' 'http://localhost:8080/service/v3/rest/1234-wxyz-123f-34ft/series?start=1437398729000&end=1437398729067&mask=foobar'
- GET: Get the current value for a point (snapshot)
curl -XGET -H 'Authorization: Basic test@example.com:password1234' 'http://localhost:8080/service/v3/rest/1234-wxyz-123f-34ft/snapshot'
- POST: Set the current value for a point (snapshot)
curl -XPOST -H 'Authorization: Basic test@example.com:password1234' -H "Content-type: application/json" -d '{"d":42.0,"dx":"any text data, json or xml","m":"Meta Data"}' 'http://localhost:8080/service/v3/rest/1234-5678-wert-zxcv/snapshot
- POST: Record a Series of Data
Note the series data needs to have a t: timestamp field, but the snapshot post will use the current time.
curl -XPOST -H 'Authorization: Basic test@example.com:password1234' -H "Content-type: application/json" -d '[{"d":42.0,"t":1437398729000,"dx":"any text data, json or xml","m":"Meta Data"},...]' 'http://localhost:8080/service/v3/rest/1234-5678-wert-zxcv/snapshot
- GET: Get All Data for a User, across all points filtered by META data
curl -XGET -H 'Authorization: Basic user@example.com:password1234' 'http://localhost:8080/service/me/series?start=1437398729000&end=1437398729067&mask=foobar'
Copyright 2016 Benjamin Sautner
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.