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: includes:
- cookbook.md.erb - cookbook.md.erb
- cookbook/sending_json.md.erb
--- ---

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

@ -1,7 +1,7 @@
# Adafruit IO API Cookbook # Adafruit IO API Cookbook
This page contains a number of recipes related to Adafruit IO which have been found useful in the past. You can add and contribute to this file by filing an `issue` on the GitHub repository, or by editing this file and submitting a pull request. This page contains a number of recipes related to Adafruit IO which have been found useful in the past. You can add and contribute to this file by filing an `issue` on the GitHub repository, or by editing this file and submitting a pull request.
## Sending and Sending image data with Adafruit IO ## Sending and Sending image data with Adafruit IO
@ -13,11 +13,10 @@ There are some important things to keep in mind when using this feature. Normal
You’ll have to do your own testing to figure out what an appropriate image size and format (png, gif, or bmp) for you are. For example, [the .png image used for testing](https://io.adafruit.com/blog/images/2016-12-14-power-switch.png) below has an on disk size of 68089 bytes, but a Base64 value of 90788 bytes, an expansion factor of about 150%, which is really close to the limit. You’ll have to do your own testing to figure out what an appropriate image size and format (png, gif, or bmp) for you are. For example, [the .png image used for testing](https://io.adafruit.com/blog/images/2016-12-14-power-switch.png) below has an on disk size of 68089 bytes, but a Base64 value of 90788 bytes, an expansion factor of about 150%, which is really close to the limit.
![base64imagepreview](https://io.adafruit.com/blog/images/2018-08-10-image-upload-size.png) ![base64imagepreview](https://io.adafruit.com/blog/images/2018-08-10-image-upload-size.png)
## Feed Identifiers ## Feed Identifiers
Names are for humans. Names are for humans.
Keys are for computers. 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. You can access a webhook by navigating to your feed and clicking the _Webhooks_ button on the right-hand sidebar.
### Raw Webhooks ### 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. 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 ### Notify Webhooks
@ -45,4 +45,4 @@ If you only want to be notified that an event has happened, rather than have to
## Floating Point Data ## Floating Point Data
If you're sending `3.1415` and only want to send `3.14` - reduce the value to the desired amount of precision in your code. You can round (up or down) or truncate this value to get it in the format you want Adafruit IO to display. If you're sending `3.1415` and only want to send `3.14` - reduce the value to the desired amount of precision in your code. You can round (up or down) or truncate this value to get it in the format you want Adafruit IO to display.

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.

468
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. 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 ## Create Data
@ -124,22 +59,7 @@ feedName->save(42, latValue, lonValue, eleValue);
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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 data 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). 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 ## Chart Feed Data
> HTTP Request > HTTP Request
@ -194,7 +168,7 @@ $ curl -H "X-AIO-Key: {io_key}" 'https://io.adafruit.com/api/v2/{username}/feeds
"hours": 1440, "hours": 1440,
"field": "avg" "field": "avg"
}, },
"columns": ["date", "value"], "columns": ["date", "avg"],
"data": [ "data": [
[ "2019-03-01T14:00:00Z", "62.579827586206896" ], [ "2019-03-01T14:00:00Z", "62.579827586206896" ],
[ "2019-03-02T18:00:00Z", "64.94642857142857" ], [ "2019-03-02T18:00:00Z", "64.94642857142857" ],
@ -203,23 +177,29 @@ $ 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 ### Path Parameters
Parameter | Type | Required | Description Parameter | Type | Required | Description
--------- | ------- | --------- | ----------------------- --------- | ------- | --------- | -----------------------
username | string | true | a valid username string username | string | true | a valid username string
feed_key | string | true | a valid feed key feed_key | string | true | a valid feed key
### Query Parameters ### Query Parameters
Parameter | Type | Required | Description Parameter | Type | Required | Description
--------- | ------- | --------- | ----------------------- --------- | ------- | --------- | -----------------------
start_time | string | false | Start time for filtering, returns records created after given time. 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. 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: > Response Sample:
```json <%= partial 'responses/data' %>
[
{
"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 data New data
@ -306,22 +270,8 @@ data = aio.receive_previous(feed.key)
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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
}
```
Data response Data response
@ -369,22 +319,7 @@ data = aio.receive_next(feed.key)
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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
}
```
Data response Data response
@ -431,22 +366,8 @@ include | string | false | List of Data record fields to include in response as
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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
}
```
Data response Data response
@ -488,24 +409,9 @@ data = aio.receive(feed.key)
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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
}
```
Data response Data response.
### Path Parameters ### 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 > HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/retain</code></div> > <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: > Response Sample:
```json ```csv
"string" "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. CSV string in `value,lat,lon,ele` format. The lat, lon, and ele values are left blank if they are not set.
@ -553,15 +459,15 @@ CSV string in `value,lat,lon,ele` format. The lat, lon, and ele values are left
### Path Parameters ### Path Parameters
Parameter | Type | Required | Description Parameter | Type | Required | Description
--------- | ------- | --------- | ----------------------- --------- | ------- | --------- | -----------------------
username | string | true | a valid username string username | string | true | a valid username string
feed_key | string | true | a valid feed key feed_key | string | true | a valid feed key
## Return Data ## Get Data Point
> HTTP Request > HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div> > <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: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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
}
```
Data response 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 > HTTP Request
> <div class="http"><span class="method-put">PUT</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div> > <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: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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
}
```
Updated Data 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 > HTTP Request
> <div class="http"><span class="method-delete">DELETE</span><code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div> > <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: > Response Sample:
```json <%= partial 'responses/datum' %>
[
{
"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 data New data
@ -795,24 +657,8 @@ group_feed_data | object | true |
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum' %>
[
{
"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
}
]
```
An array of data An array of data
@ -846,22 +692,8 @@ feed_key | string | true | a valid feed key
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum' %>
{
"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 data New data
@ -902,24 +734,8 @@ datum | object | true | Data record including a `value` field (required) and opt
> Response Sample: > Response Sample:
```json <%= partial 'responses/data' %>
[
{
"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 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). 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 > HTTP Request
> <div class="http"><span class="method-put">PUT</span><code class="path">/api/v2/{username}/feeds/{feed_key}</code></div> > <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
Webhooks are how REST-API supporting sites support data ‘pushing’. For example, say you wanted to get a user’s latest Twitter message. 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.
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"> <aside class="notice">
These data publishing webhook methods <strong>do not require authentication</strong>. That 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. 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 > HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token</code></div> > <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token</code></div>
```shell ```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 ```python
@ -35,34 +41,40 @@ $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:to
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum', locals: {value: '42'} %>
{
"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 ### 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 > HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/raw</code></div> > <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/raw</code></div>
```shell ```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 ```python
@ -76,34 +88,24 @@ $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:to
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum', locals: { value: "this is raw data, { 'not properly formatted 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
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
token | string | true | the webhook token
## Trigger a Notification ## Send Notification via Webhook
> HTTP Request > HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/notify</code></div> > <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/notify</code></div>
```shell ```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 ```python
@ -117,27 +119,9 @@ $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/webhooks/feed/:to
> Response Sample: > Response Sample:
```json <%= partial 'responses/datum', locals: { value: "ping"} %>
{
"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.
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: includes:
- mqtt/mqtt_index.md.erb - mqtt/mqtt_index.md.erb
- mqtt/_mqtt_qos.md.erb - mqtt/mqtt_qos.md.erb
- mqtt/_mqtt_data_format.md.erb - mqtt/mqtt_data_format.md.erb
- mqtt/mqtt_topics.md.erb - mqtt/mqtt_topics.md.erb
- mqtt/mqtt_group_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"
}
```