adafruit-mirror/Adafruit_IO_Documentation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

update webhook docs, add JSON formatting to cookbook

Browse source
This commit is contained in:
Adam Bachman 2019-05-22 14:22:33 -04:00
parent 5ea821b79d
commit 60df2a85c7
9 changed files with 276 additions and 442 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
source/cookbook.html.erb
View file

@ -24,6 +24,7 @@ toc_footers:
includes:
- cookbook.md.erb
- cookbook/sending_json.md.erb
---

2
source/includes/_cookbook.md.erb
View file

@ -17,7 +17,6 @@ You’ll have to do your own testing to figure out what an appropriate image siz
## Feed Identifiers
Names are for humans.
Keys are for computers.
@ -37,6 +36,7 @@ Webhook receiver URLs give you a limited use, unique API address that you can se
You can access a webhook by navigating to your feed and clicking the _Webhooks_ button on the right-hand sidebar.
### Raw Webhooks
If you want to receive the whole contents of webhook events--for example, when receiving webhook notifications from a service like Slack or GitHub where you don't have control over the payload the service is sending--add `/raw` to the end of the Adafruit IO webhook URL that you share with the service.
### Notify Webhooks

80
source/includes/cookbook/_sending_json.md.erb Normal file
View file

@ -0,0 +1,80 @@
## Sending and Storing JSON
```json
{
"value": 22.587,
"lat": 38.1123,
"lon": -91.2325,
"ele": 112
}
```
Because Adafruit IO supports additional features beyond a basic MQTT brokering service, such as location tagging for data points, the service supports data in the JSON format described in the [HTTP create data API description](/#create-data).
This lets us store the individual value, `22.587`, and data about the value: its latitude, longitude, and elevation. Data about the data is "metadata"!
But what happens when the value you want to send is itself JSON? Good news! There are a few solutions available to you in that situation.
### Double encoded JSON strings
```javascript
JSON.stringify({
"value": JSON.stringify({"sensor-1":22.587,"sensor-2":13.182})
})
```
**The safest way to can send JSON data as a value** is to "double encode" it before sending, in which case IO will treat it as a raw string. If you're using something like javascript's `JSON.stringify` function or Ruby's `JSON.generate`, double encoding means passing the result of `JSON.stringify` through `JSON.stringify` a second time
The double encoded JSON string can be sent directly through Adafruit IO without interference from our processing system, because the processing system will not interpret it as JSON. In your receiving code, because the value passed through includes surrounding double quotes, you have to call your parse function twice to restore the JSON object.
`JSON.parse(JSON.parse(input))`
### IO formatted JSON
```json
{
"value": {"sensor-1":22.587,"sensor-2":13.182},
"lat": 38.1123,
"lon": -91.2325,
"ele": 112
}
```
The simplest way to send JSON data to Adafruit IO is include it directly in the datum formatted record you send to IO. For example, if instead of 22.587, I wanted to send something like, {"sensor-1":22.587,"sensor-2":13.182}, the "wrapped" version would look like the value on the right.
It's worth noting that because Adafruit IO parses the entire JSON object that you send it, any valid JSON will be parsed and when it is stored in our system and forwarded to any subscribers, it will be regenerated. The significance of that is that if you publish JSON data with whitespace, it will be stored and republished without whitespace, because our generator produces the most compact JSON format possible.
### Non-IO formatted JSON
```
curl -H "Content-Type: application/json" \
-H "X-AIO-Key: toomanysecrets" \
--data '{"sensor-1":22.587,"sensor-2":13.182}' \
https://io.adafruit.com/api/v2/username/feeds/feed-key/data
```
Another way you can send raw JSON data is to just send it. If Adafruit IO doesn't find a "value" key in the JSON object you send, it will treat the whole blob as plain text and store and forward the data. That means with our example JSON object, sending the string `{"sensor-1":22.587,"sensor-2":13.182}` will result in `{"sensor-1":22.587,"sensor-2":13.182}` being stored in IO and sent to MQTT subscribers.
**NOTE:** This solution is the riskiest, because if your JSON blob includes the key named `value`, then IO will interpret _that_ as the value you want to store and ignore all the other keys.
### That's not JSON at all!
```javascript
btoa(JSON.stringify({ "something": "here" }))
// "eyJzb21ldGhpbmciOiJoZXJlIn0="
atob("eyJzb21ldGhpbmciOiJoZXJlIn0=")
// {"something":"here"}
```
If you want to be absolutely sure that Adafruit IO will not interfere with the data you're sending, encode it as a [Base64](https://en.wikipedia.org/wiki/Base64) string first.
This solution is also ideal if you want to store or send binary data with Adafruit IO. You won't get to see any pretty charts, but your data will remain exactly the way you left it.

448
source/includes/http/_data.md.erb
View file

@ -6,71 +6,6 @@ You can create, read, update, or delete data records. Every **CREATE**, **UPDATE
Data points belong to feeds, so every Data API call starts with a Feed URL.
## Get Feed Data
> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data</code></div>
```shell
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data
```
```cpp
// Not implemented in Adafruit IO Arduino
```
```python
# Not implemented in Adafruit IO Python
# Not implemented in Adafruit IO CircuitPython
```
> Response Sample:
```json
[
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
]
```
### Response Parameters
An array of zero or more data points.
This API is paginated.
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key
### Query Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
start_time | string | false | Start time for filtering, returns records created after given time.
end_time | string | false | End time for filtering, returns records created before give time.
limit | integer | false | Limit the number of records returned.
include | string | false | List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.
before | string | false | System generated token used to produce the next page of data. See [The Link Header](#the-link-header) for details.
## Create Data
@ -124,22 +59,7 @@ feedName->save(42, latValue, lonValue, eleValue);
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
New data
@ -159,6 +79,60 @@ Parameter | Type | Required | Description
datum | object | true | Data record including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).
## Get Feed Data
> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data</code></div>
```shell
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data
```
```cpp
// Not implemented in Adafruit IO Arduino
```
```python
# Not implemented in Adafruit IO Python
# Not implemented in Adafruit IO CircuitPython
```
> Response Sample:
<%= partial 'responses/data' %>
### Response Parameters
An array of zero or more data points.
This API is paginated.
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
feed_key | string | true | a valid feed key
### Query Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
start_time | string | false | Start time for filtering, returns records created after given time.
end_time | string | false | End time for filtering, returns records created before give time.
limit | integer | false | Limit the number of records returned.
include | csv string | false | List of Data record fields to include in response records. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.
before | string | false | System generated token used to produce the next page of data. See [The Link Header](#the-link-header) for details.
## Chart Feed Data
> HTTP Request
@ -194,7 +168,7 @@ $ curl -H "X-AIO-Key: {io_key}" 'https://io.adafruit.com/api/v2/{username}/feeds
"hours": 1440,
"field": "avg"
},
"columns": ["date", "value"],
"columns": ["date", "avg"],
"data": [
[ "2019-03-01T14:00:00Z", "62.579827586206896" ],
[ "2019-03-02T18:00:00Z", "64.94642857142857" ],
@ -203,7 +177,9 @@ $ curl -H "X-AIO-Key: {io_key}" 'https://io.adafruit.com/api/v2/{username}/feeds
}
```
A JSON record containing chart data and the parameters used to generate it.
A JSON record containing chart data and the parameters used to generate it. This API will automatically calculate `resolution` based on the optimal time slice for the given `start_time` to `end_time` range or `hours` value given.
Charts on io.adafruit.com use this API with only the `hours` parameter to render charts on dashboards and feed pages.
### Path Parameters
@ -220,6 +196,10 @@ Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
start_time | string | false | Start time for filtering, returns records created after given time.
end_time | string | false | End time for filtering, returns records created before give time.
resolution | int | false | Size of aggregation slice in minutes. Must be one of: `1`, `5`, `10`, `30`, `60`, `120`, `240`, `480`, or `960`
hours | int | false | Number of hours to include in the chart. This value is ignored if `start_time` and `end_time` are given.
field | string | false | Aggregate field to return. Must be one of: `avg`, `sum`, `val`, `min`, `max`, `val_count`
raw | boolean | false | Force raw chart data to be returned. Not compatible with `field` or `resolution` parameters. Use `1` or `true` for boolean true value.
@ -248,24 +228,8 @@ aio.send_batch_data(feed_name.key, data_list)
> Response Sample:
```json
[
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
]
```
<%= partial 'responses/data' %>
New data
@ -306,22 +270,8 @@ data = aio.receive_previous(feed.key)
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
Data response
@ -369,22 +319,7 @@ data = aio.receive_next(feed.key)
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
Data response
@ -431,22 +366,8 @@ include | string | false | List of Data record fields to include in response as
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
Data response
@ -488,24 +409,9 @@ data = aio.receive(feed.key)
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
Data response
Data response.
### Path Parameters
@ -525,7 +431,7 @@ include | string | false | List of Data record fields to include in response as
## Get Last Data (CSV)
## Get Most Recent Data
> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/retain</code></div>
@ -544,8 +450,8 @@ include | string | false | List of Data record fields to include in response as
> Response Sample:
```json
"string"
```csv
"string",0.0,0.0,0.0
```
CSV string in `value,lat,lon,ele` format. The lat, lon, and ele values are left blank if they are not set.
@ -561,7 +467,7 @@ feed_key | string | true | a valid feed key
## Return Data
## Get Data Point
> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div>
@ -585,22 +491,8 @@ data = aio.receive(feed_name['key'])
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
Data response
@ -623,7 +515,7 @@ include | string | false | List of Data record fields to include in response as
## Replace Data
## Update Data Point
> HTTP Request
> <div class="http"><span class="method-put">PUT</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div>
@ -642,22 +534,8 @@ include | string | false | List of Data record fields to include in response as
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
Updated Data
@ -679,7 +557,7 @@ datum | object | true | Data record including a `value` field (required) and opt
## Delete Data
## Delete Data Point
> HTTP Request
> <div class="http"><span class="method-delete">DELETE</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div>
@ -738,24 +616,8 @@ id | string | true |
> Response Sample:
```json
[
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
]
```
<%= partial 'responses/datum' %>
New data
@ -795,24 +657,8 @@ group_feed_data | object | true |
> Response Sample:
```json
[
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
]
```
<%= partial 'responses/datum' %>
An array of data
@ -846,22 +692,8 @@ feed_key | string | true | a valid feed key
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum' %>
New data
@ -902,24 +734,8 @@ datum | object | true | Data record including a `value` field (required) and opt
> Response Sample:
```json
[
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
]
```
<%= partial 'responses/data' %>
New data
@ -939,87 +755,3 @@ Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
data | array | true | A collection of data records including `value` (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).
## Send Data to a Feed via Webhook
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token</code></div>
```shell
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
New feed data record
## Send Arbitrary Data to Feed via Webhook
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/raw</code></div>
```shell
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
Returns a new feed data record.
**NOTE:** This method **does not require authentication**.

2
source/includes/http/_feeds.md.erb
View file

@ -352,7 +352,7 @@ feed_key | string | true | a valid feed key
## Replace a Feed
## Update Feed
> HTTP Request
> <div class="http"><span class="method-put">PUT</span><code class="path">/api/v2/{username}/feeds/{feed_key}</code></div>

118
source/includes/http/_webhooks.md.erb
View file

@ -1,11 +1,8 @@
# Webhooks
Webhooks are how REST-API supporting sites support data ‘pushing’. For example, say you wanted to get a user’s latest Twitter message.
Instead of constantly connecting to the twitter API every minute to check if a new message has been posted, you can ask Twitter to update a webhook
URL on each post. That means Twitter will contact you when there’s new data. But, as you can imagine, you need a webserver to listen for that posting.
In this case, Adafruit IO can act as that webhook destination.
Webhooks are one way disconnected web services can share data with each other, automatically. For example, say you wanted to get a user’s latest Twitter message. Instead of constantly connecting to the twitter API every minute to check if a new message has been posted, you can ask Twitter to update a webhook URL on each post. That means Twitter will contact you when there’s new data. But, as you can imagine, you need a webserver to listen for that posting. In this case, Adafruit IO can act as that webhook destination.
Adafruit IO only supports receiving data at this time, we need a service that will publish data into a feed.
Adafruit IO only supports receiving data at this time.
<aside class="notice">
These data publishing webhook methods <strong>do not require authentication</strong>. That
@ -15,13 +12,22 @@ authentication data.
You can create new feed webhook receivers by visiting a feed page and using the "Webhooks" link.
## Send Data
## Send Data via Webhook
Create a data value. The request body should be the same as the [create data method](#create-data).
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token</code></div>
```shell
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:token
# publish as form data
curl -F "value=42" https://io.adafruit.com/api/v2/webhooks/feed/:token
# publish as JSON
curl -F '{"value":"42"}' -H 'Content-Type: application/json' \
https://io.adafruit.com/api/v2/webhooks/feed/:token
```
```python
@ -35,34 +41,40 @@ $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:to
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
New feed data record
<%= partial 'responses/datum', locals: {value: '42'} %>
## Send Arbitrary Data
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
token | string | true | the webhook token
### Body Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
value | string | true | Data value
lat | float | false | latitude value for location
lon | float | false | longitude value for location
ele | float | false | elevation value for location
## Send Arbitrary Data via Webhook
New feed data record whose value is the raw contents of the webhook request body.
Use this path if the web service you're connecting to can't be configured to match the webhook `Send Data` API body format.
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/raw</code></div>
```shell
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:token/raw
curl -H "Content-Type: text/plain" \
--data "this is raw data, { 'not properly formatted json' }" \
https://io.adafruit.com/api/v2/webhooks/feed/:token/raw
```
```python
@ -76,34 +88,24 @@ $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:to
> Response Sample:
```json
{
"id": "string",
"value": "string",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
<%= partial 'responses/datum', locals: { value: "this is raw data, { 'not properly formatted json' }"} %>
New feed data record
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
token | string | true | the webhook token
## Trigger a Notification
## Send Notification via Webhook
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/notify</code></div>
```shell
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:token/notify
$ curl -X POST https://io.adafruit.com/api/v2/webhooks/feed/:token/notify
```
```python
@ -117,27 +119,9 @@ $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:to
> Response Sample:
```json
{
"id": "string",
"value": "ping",
"feed_id": 0,
"group_id": 0,
"expiration": "string",
"lat": 0,
"lon": 0,
"ele": 0,
"completed_at": "string",
"created_at": "string",
"updated_at": "string",
"created_epoch": 0
}
```
New feed data record.
<%= partial 'responses/datum', locals: { value: "ping"} %>
Creates a new feed data record with the value "ping", regardless of what was posted.
This path is helpful if you're using a low-memory MQTT client that can't handle the large webhook payloads that a service like GitHub publishes and all you care about is _that_ something happened, not _precisely what_ happened.

4
source/mqtt.html.erb
View file

@ -25,8 +25,8 @@ toc_append:
includes:
- mqtt/mqtt_index.md.erb
- mqtt/_mqtt_qos.md.erb
- mqtt/_mqtt_data_format.md.erb
- mqtt/mqtt_qos.md.erb
- mqtt/mqtt_data_format.md.erb
- mqtt/mqtt_topics.md.erb
- mqtt/mqtt_group_topics.md.erb

19
source/responses/_data.md.erb Normal file
View file

@ -0,0 +1,19 @@
<% value = 'string' unless defined?(value) %>
```json
[
{
"id": "string",
"value": "<%= value || 'string' %>",
"feed_id": 0,
"feed_key": "string",
"created_at": "datetime",
"location": {},
"lat": 0.0,
"lon": 0.0,
"ele": 0.0,
"created_epoch": 0,
"expiration": "datetime"
}
]
```

18
source/responses/_datum.md.erb Normal file
View file

@ -0,0 +1,18 @@
<% value = 'string' unless defined?(value) %>
```json
{
"id": "string",
"value": "<%= value || 'string' %>",
"feed_id": 0,
"feed_key": "string",
"created_at": "datetime",
"location": {},
"lat": 0.0,
"lon": 0.0,
"ele": 0.0,
"created_epoch": 0,
"expiration": "datetime"
}
```