adafruit-mirror/Adafruit_IO_Documentation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
Adafruit_IO_Documentation/source/includes/http/_groups.md.erb
tyeth 2f8db6bc91 Datums - Update parameter tables for datum endpoints 
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
2024-10-24 09:24:33 +01:00

1015 lines
21 KiB
Text
Raw Blame History

# Groups
> A Group Record
```json
{
"id": 0,
"name": "string",
"description": "string",
"feeds": [
{
"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",
"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"
}
],
"created_at": "string",
"updated_at": "string"
}
```
Groups are a set of Feeds. They're used for publishing and reading to multiple feeds at a time.
For example, if you are building a weather station, you would add feeds for `humidity` and `temperature` to a new `weatherstation` group.
You can create, read, update, or delete group records. Every **CREATE**, **UPDATE**, or **DELETE** action on a group record counts against your rate limit.
There is also an endpoint for submitting multiple feed values to a group, see the **groups/{groupname}/data** endpoint.
## Get All Groups
> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/groups</code></div>
```shell
$ curl -H "X-AIO-Key: {your_aio_key}" http://io.adafruit.com/api/v2/{your_username}/groups
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
[
{
"id": 0,
"name": "string",
"description": "string",
"feeds": [
{
"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"
}
],
"created_at": "string",
"updated_at": "string"
}
]
```
An array of groups with their respective feeds .
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
## Create Group
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/groups</code></div>
```shell
$ curl -F 'name=New Group' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/
```
```python
```
```cpp
AdafruitIO_Group *group = io.group("example");
```
```ruby
```
> Response Sample:
```json
{
"id": 0,
"name": "string",
"description": "string",
"feeds": [
{
"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"
}
],
"created_at": "string",
"updated_at": "string"
}
```
New Group
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
### Body Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
group | object | true |
## Get Group
> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/groups/{group_key}</code></div>
```shell
curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
{
"id": 0,
"name": "string",
"description": "string",
"feeds": [
{
"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"
}
],
"created_at": "string",
"updated_at": "string"
}
```
Group response
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |
## Update Group
> HTTP Request
> <div class="http"><span class="method-put">PUT</span><code class="path">/api/v2/{username}/groups/{group_key}</code></div>
```shell
$ curl -F 'name=Group' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
{
"id": 0,
"name": "string",
"description": "string",
"feeds": [
{
"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"
}
],
"created_at": "string",
"updated_at": "string"
}
```
Updated group
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |
### Body Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
group | object | true |
## Delete Group
> HTTP Request
> <div class="http"><span class="method-delete">DELETE</span><code class="path">/api/v2/{username}/groups/{group_key}</code></div>
```shell
$ curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
"string"
```
Deleted Group successfully
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |
## Create Feed in a Group
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/groups/{group_key}/feeds</code></div>
```shell
$ curl --data '{"feed": {"name": "Feed Name"}}' \
-H "Content-Type: application/json" \
-H "X-AIO-Key: {io_key}" \
https://io.adafruit.com/api/v2/{username}/groups/{group_key}/feeds
```
```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"
}
```
New feed
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
username | string | true | a valid username string
group_key | string | true |
### Body Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
feed | object | true |
## Add Feed to Group
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/groups/{group_key}/add</code></div>
```shell
$ curl -F 'feed_key={feed_key}' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/add
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
{
"id": 0,
"name": "string",
"description": "string",
"feeds": [
{
"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"
}
],
"created_at": "string",
"updated_at": "string"
}
```
Returns updated group.
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
group_key | string | true |
username | string | true | a valid username string
### Query Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
feed_key | string | false |
## Remove Feed from Group
> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/{username}/groups/{group_key}/remove</code></div>
```shell
$ curl -F 'feed_key={feed_key}' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/remove
```
```python
```
```cpp
```
```ruby
```
> Response Sample:
```json
{
"id": 0,
"name": "string",
"description": "string",
"feeds": [
{
"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"
}
],
"created_at": "string",
"updated_at": "string"
}
```
Updated group
### Path Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
group_key | string | true |
username | string | true | a valid username string
### Query Parameters
Parameter | Type | Required | Description
--------- | ------- | --------- | -----------------------
feed_key | string | false |
## Get Group Feeds
> HTTP Request
> <div class="http"><span class="method-get">GET</span><code class="path">/api/v2/{username}/groups/{group_key}/feeds</code></div>
```shell
$ curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/feeds
```
```python
```
```cpp
```
```ruby
```
> 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
--------- | ------- | --------- | -----------------------
group_key | string | true |
username | string | true | a valid username string
Reference in a new issue View git blame Copy permalink