2f8db6bc91
Adds instructions about submitting multiple data points in one operation. Swaps the parameter name from datum to "Request Body" for single data endpoints. Fixes #58
615 lines
13 KiB
Text
615 lines
13 KiB
Text
# Feeds
|
|
|
|
Feeds are the core of the Adafruit IO system. The feed holds metadata about the data you push to Adafruit IO. This includes settings for whether the data is public or private, what license the stored data falls under, and a general description of the data. The feed also contains the sensor data values that get pushed to Adafruit IO from your device.
|
|
|
|
You will need to create one feed for each unique source of data you send to Adafruit IO.
|
|
|
|
You can create, read, update, or delete feeds. Every **CREATE**, **UPDATE**, or **DELETE** action on a feed record counts against your rate limit.
|
|
|
|
There are also endpoints for submitting multiple data points to a feed, or multiple feed values to a group, see **feeds/{feed_key}/batch** and **groups/{groupname}/data** endpoints.
|
|
|
|
## All Feeds
|
|
|
|
> HTTP Request
|
|
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds</code></div>
|
|
|
|
```shell
|
|
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/
|
|
```
|
|
|
|
```python
|
|
# Adafruit IO Python
|
|
feeds = aio.feeds()
|
|
|
|
# Not implemented in Adafruit IO CircuitPython
|
|
```
|
|
|
|
> Response Sample:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"key": "string",
|
|
"group": {
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
},
|
|
"groups": [
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
],
|
|
"description": "string",
|
|
"details": {
|
|
"shared_with": null,
|
|
"data": {
|
|
"first": {
|
|
"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
|
|
},
|
|
"last": {
|
|
"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
|
|
},
|
|
"count": 0
|
|
}
|
|
},
|
|
"unit_type": "string",
|
|
"unit_symbol": "string",
|
|
"history": true,
|
|
"visibility": "string",
|
|
"license": "string",
|
|
"enabled": true,
|
|
"last_value": "string",
|
|
"status": "string",
|
|
"status_notify": true,
|
|
"status_timeout": 0,
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
]
|
|
```
|
|
|
|
An array of feeds
|
|
|
|
|
|
### Path Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
username | string | true | a valid username string
|
|
|
|
|
|
|
|
## Create Feed
|
|
|
|
> HTTP Request
|
|
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/feeds</code></div>
|
|
|
|
```shell
|
|
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
|
|
--data '{"feed": {"name": "New Feed"}}' \
|
|
/{username}/feeds
|
|
```
|
|
|
|
```cpp
|
|
AdafruitIO_Feed *newFeed = io.feed("newfeed");
|
|
```
|
|
|
|
```python
|
|
# Adafruit IO Python
|
|
new_feed = Feed(name="newfeed")
|
|
aio.create_feed(new_feed)
|
|
|
|
# Adafruit IO CircuitPython
|
|
new_feed = io.create_new_feed('newfeed')
|
|
```
|
|
|
|
```ruby
|
|
puts "create"
|
|
Feed = api.create_feed(name: "Feed #{SecureRandom.hex(4)}")
|
|
```
|
|
|
|
> Response Sample:
|
|
|
|
```json
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"key": "string",
|
|
"group": {
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
},
|
|
"groups": [
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
],
|
|
"description": "string",
|
|
"details": {
|
|
"shared_with": null,
|
|
"data": {
|
|
"first": {
|
|
"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
|
|
},
|
|
"last": {
|
|
"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
|
|
},
|
|
"count": 0
|
|
}
|
|
},
|
|
"unit_type": "string",
|
|
"unit_symbol": "string",
|
|
"history": true,
|
|
"visibility": "string",
|
|
"license": "string",
|
|
"enabled": true,
|
|
"last_value": "string",
|
|
"status": "string",
|
|
"status_notify": true,
|
|
"status_timeout": 0,
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
```
|
|
|
|
New feed
|
|
|
|
|
|
### Path Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
username | string | true | a valid username string
|
|
|
|
|
|
### Query Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
group_key | string | false |
|
|
|
|
|
|
### Body Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
feed | object | true |
|
|
|
|
|
|
|
|
## Get Feed
|
|
|
|
> HTTP Request
|
|
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}</code></div>
|
|
|
|
```shell
|
|
$ curl -H "X-AIO-Key: {io_key}" /{username}/feeds/{feed_key}
|
|
```
|
|
|
|
```python
|
|
# Adafruit IO Python
|
|
new_feed = aio.feeds('feedkey')
|
|
|
|
# Adafruit IO CircuitPython
|
|
new_feed = io.get_feed('feedkey')
|
|
```
|
|
|
|
```ruby
|
|
puts "read?"
|
|
# ... get 404
|
|
begin
|
|
api.feed(feedname['key'])
|
|
rescue => ex
|
|
if ex.response.status === 404
|
|
puts "expected error #{ex.response.status}: #{ex.message}"
|
|
else
|
|
puts "unexpected error! #{ex.message}"
|
|
end
|
|
end
|
|
|
|
```
|
|
|
|
> Response Sample:
|
|
|
|
```json
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"key": "string",
|
|
"group": {
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
},
|
|
"groups": [
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
],
|
|
"description": "string",
|
|
"details": {
|
|
"shared_with": null,
|
|
"data": {
|
|
"first": {
|
|
"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
|
|
},
|
|
"last": {
|
|
"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
|
|
},
|
|
"count": 0
|
|
}
|
|
},
|
|
"unit_type": "string",
|
|
"unit_symbol": "string",
|
|
"history": true,
|
|
"visibility": "string",
|
|
"license": "string",
|
|
"enabled": true,
|
|
"last_value": "string",
|
|
"status": "string",
|
|
"status_notify": true,
|
|
"status_timeout": 0,
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
```
|
|
|
|
Feed response
|
|
|
|
|
|
### Path Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
username | string | true | a valid username string
|
|
feed_key | string | true | a valid feed key
|
|
|
|
|
|
|
|
## Update Feed
|
|
|
|
> HTTP Request
|
|
> <div class="http"><span class="method-put">PUT</span><code class="path">/api/v2/{username}/feeds/{feed_key}</code></div>
|
|
|
|
|
|
```shell
|
|
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}
|
|
```
|
|
|
|
```cpp
|
|
// Not implemented in Adafruit IO Arduino
|
|
```
|
|
|
|
```python
|
|
# Not implemented in Adafruit IO Python
|
|
|
|
# Not implemented in Adafruit IO CircuitPython
|
|
```
|
|
|
|
|
|
> Response Sample:
|
|
|
|
```json
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"key": "string",
|
|
"group": {
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
},
|
|
"groups": [
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
],
|
|
"description": "string",
|
|
"details": {
|
|
"shared_with": null,
|
|
"data": {
|
|
"first": {
|
|
"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
|
|
},
|
|
"last": {
|
|
"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
|
|
},
|
|
"count": 0
|
|
}
|
|
},
|
|
"unit_type": "string",
|
|
"unit_symbol": "string",
|
|
"history": true,
|
|
"visibility": "string",
|
|
"license": "string",
|
|
"enabled": true,
|
|
"last_value": "string",
|
|
"status": "string",
|
|
"status_notify": true,
|
|
"status_timeout": 0,
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
```
|
|
|
|
Updated feed
|
|
|
|
|
|
### Path Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
username | string | true | a valid username string
|
|
feed_key | string | true | a valid feed key
|
|
|
|
|
|
### Body Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
feed | object | true |
|
|
|
|
|
|
|
|
## Delete Feed
|
|
|
|
> HTTP Request
|
|
> <div class="http"><span class="method-delete">DELETE</span><code class="path">/api/v2/{username}/feeds/{feed_key}</code></div>
|
|
|
|
```shell
|
|
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}
|
|
```
|
|
|
|
```python
|
|
# Adafruit IO Python
|
|
io.delete_feed(feed_name.key)
|
|
|
|
# Adafruit IO CircuitPython
|
|
io.delete_feed(feed_name['key'])
|
|
```
|
|
|
|
```ruby
|
|
puts "delete"
|
|
api.delete_feed(feed)
|
|
```
|
|
|
|
> Response Sample:
|
|
|
|
```json
|
|
|
|
```
|
|
|
|
Deleted feed successfully
|
|
|
|
|
|
### Path Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
username | string | true | a valid username string
|
|
feed_key | string | true | a valid feed key
|
|
|
|
|
|
|
|
## Get Feed
|
|
|
|
> HTTP Request
|
|
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/feeds/{feed_key}/details</code></div>
|
|
|
|
```shell
|
|
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/details
|
|
```
|
|
|
|
```cpp
|
|
// Not implemented in Adafruit IO Arduino
|
|
```
|
|
|
|
```python
|
|
# Not implemented in Adafruit IO Python
|
|
|
|
# Not implemented in Adafruit IO CircuitPython
|
|
```
|
|
|
|
```ruby
|
|
puts "read"
|
|
puts JSON.pretty_generate(api.feed_details(feed))
|
|
```
|
|
|
|
> Response Sample:
|
|
|
|
```json
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"key": "string",
|
|
"group": {
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
},
|
|
"groups": [
|
|
{
|
|
"id": 0,
|
|
"name": "string",
|
|
"description": "string",
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
],
|
|
"description": "string",
|
|
"details": {
|
|
"shared_with": null,
|
|
"data": {
|
|
"first": {
|
|
"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
|
|
},
|
|
"last": {
|
|
"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
|
|
},
|
|
"count": 0
|
|
}
|
|
},
|
|
"unit_type": "string",
|
|
"unit_symbol": "string",
|
|
"history": true,
|
|
"visibility": "string",
|
|
"license": "string",
|
|
"enabled": true,
|
|
"last_value": "string",
|
|
"status": "string",
|
|
"status_notify": true,
|
|
"status_timeout": 0,
|
|
"created_at": "string",
|
|
"updated_at": "string"
|
|
}
|
|
```
|
|
|
|
Feed response
|
|
|
|
|
|
### Path Parameters
|
|
|
|
Parameter | Type | Required | Description
|
|
--------- | ------- | --------- | -----------------------
|
|
username | string | true | a valid username string
|
|
feed_key | string | true | a valid feed key
|