-
Notifications
You must be signed in to change notification settings - Fork 17
/
apiary.apib
270 lines (203 loc) · 10.8 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
FORMAT: 1A
HOST: https://groker.init.st/api
# Initial State Streaming API
This is documentation on the Initial State HTTP API for sending data to an Initial State account.
To fetch data from your account, check out the [Read API documentation](https://initialstatereadapi.docs.apiary.io/).
# Group Rate Limiting
This API is rate limited on a per-account basis. You can see your current rate limit status by investigating the headers on the response to `/events`. This table describes the rate limit headers:
|header|description|
|------------------------|-----|
|`X-RateLimit-Limit`|This is the current number of requests per 10 second interval. This value is based on your account plan and `accessKey` rights.|
|`X-RateLimit-Remaining`|This is the number of requests left from the `X-RateLimit-Limit` during a 10 second interval.|
|`X-RateLimit-Reset`|This is a Unix epoch in seconds indicating when the `X-RateLimit-Remaining` will be reset back to the value of `X-RateLimit-Limit`.|
|`Retry-After`|This header is *only* returned during a rate limited request represented by an HTTP 429 Status Code. This value will provide a number of seconds requesting code should wait before retrying the request.|
# Group Versioning
This api is versioned with **semver** style versions, if you're not familiar with semver, check it out [here](http://semver.org/). The api respects the `Accept-Version` HTTP header to provide predictable request/response versioning. You can check the current supported versions by performing a `GET` on the `/versions` route. If you don't include an `Accept-Version` header, the api assumes that you want the latest version. The value of `Accept-Version` can be specified like NPM dependencies.
## Versions [/versions]
A `version` is a string `semver`.
### Get supported versions [GET]
+ Response 200 (application/json)
+ Body
[
"0.0.1",
"0.0.2",
"0.0.3",
"0.0.4"
]
# Group Event Buckets
**Buckets** are groupings of `event` data. They associate events together by a unique `bucketKey`. The `bucketKey`s uniqueness is scoped to an access key, so two buckets with the same bucketKey on two different access keys will result in two unique buckets.
## Buckets JSON [/buckets]
A `bucket` is a collection of `event` data.
Common Successful Response Scenarios:
- `201`: If a `POST` is made to `/buckets` with a accessKey/bucketKey combination that is unique, doesn't exist, and can be created, the api will respond with a `201` Created response.
- `204`: If a `POST` is made to `/buckets` with a accessKey/bucketKey combination that has already been created, the api will respond with a `204` No Content response.
**Authentication**
Authentication is handled via Access Keys generated from within your [Initial State account](https://www.initialstate.com/). An example access key looks like this: `ist_fakee8do2JQN3Eos8Ah2FS8uiFD3Ola2`. An Access Key can be provided as an HTTP header, or as a url parameter.
> NOTE: Initial State IoT has access keys that are prefixed with `ist_`. To ensure you're using the latest IoT platform processing path, use `ist_` prefixed access keys.
|type|name/key|
|----|-----|
|HTTP Header|`X-IS-AccessKey`|
|URL Parameter|`accessKey`|
**Bucket Entity**
|parameter|required|type|illegal characters|length limit|notes|
|---------|--------|----|-----|---|---|
|bucketKey|*true*|`string`| `:`, `"`, `'`|250 characters|associates event data|
|bucketName|*false*|`string`|none|250 characters|friendly name of the bucket, shows in the bucket shelf in the UI|
### Create a bucket [POST]
+ Request
+ Header
Content-Type: application/json
X-IS-AccessKey: 1234
Accept-Version: ~0
+ Body
{
"bucketKey": "apiary_bucket",
"bucketName": "Apiary Bucket"
}
+ Response 201 (application/json)
+ Response 204
+ Response 401
+ Response 403 (text/plain)
+ Body
"ACCESS_DENIED_KEY"
+ Response 500
## Buckets no-JSON [/buckets?accessKey={accessKey}&bucketKey={bucketKey}&bucketName={bucketName}]
A `bucket` is a collection of `event` data.
Common Successful Response Scenarios:
- `201`: If a `POST` is made to `/buckets` with a accessKey/bucketKey combination that is unique, doesn't exist, and can be created, the api will respond with a `201` Created response.
- `204`: If a `POST` is made to `/buckets` with a accessKey/bucketKey combination that has already been created, the api will respond with a `204` No Content response.
**Authentication**
Authentication is handled via Access Keys generated from within your [Initial State account](https://www.initialstate.com/). An example access key looks like this: `ist_fakee8do2JQN3Eos8Ah2FS8uiFD3Ola2`. An Access Key can be provided as an HTTP header, or as a url parameter
|type|name/key|
|----|-----|
|HTTP Header|`X-IS-AccessKey`|
|URL Parameter|`accessKey`|
+ Parameters
+ accessKey (required, string, `ist_fakee8do2JQN3Eos8Ah2FS8uiFD3Ola2`) ... Access Key
+ bucketKey (required, string, `bucket1sfa`) ... Unique Bucket Key
+ bucketName (optional, string, `My New Bucket`) ... Friendly Bucket Name
### Create a bucket [POST]
+ Response 201 (application/json)
+ Response 204
+ Response 401
+ Response 403 (text/plain)
+ Body
"ACCESS_DENIED_KEY"
+ Response 500
# Group Event Data
These endpoints are related to the `events` resource. An `event` is simply a data point with a timestamp.
## Events JSON [/events]
### Send Events [POST]
This is the main endpoint for shipping data to Initial State's Events Api. The data is sent in an array of JSON objects that represent individual events. You can submit one event or an array of events where the body size is not larger than 1 megabyte.
**Limits**
|type|limit|exceeded response HTTP status code|
|----|-----|----------------------|
|`Content-Length`|<= 1 megabyte|`413` Request Entity Too Large|
|request rate|3 r/s (for non-enterprise)|`429` Too Many Requests|
**Recommended Max Throughput**
- 3 r/s with 10 events/request
**Custom Headers**
|name|notes|
|----|-----|
|`X-IS-AccessKey`|This is the access key generated from Initial State account|
|`X-IS-BucketKey`|This is a user generated key and can be any string exluding characters `:`, `"`, `'`. See *Bucket Creation* endpoint|
**Event JSON Entity**
> **Note**: JSON events can be sent as either a single object at the root of the http body i.e. `{"key": "temp", "value": 32}`, or inside an array at the root of the HTTP body `[{"key": "temp", "value": 32}]`
|name|required|type|max length|notes|
|----|----|-----|---|---|
|key |*true*|`string`|100 characters|stream key name|
|value |*true*|`string`, `bool`, or `number`|2000 characters|stream value|
|epoch |*false*|`number`||epoch is in seconds with fractional seconds to right of decimal.|
|iso8601|*false*|`string`||ISO-8601 Timestamp|
> **Timestamping**: If the client doesn't provide a timestamp, a server timestamp will be automatically provided. If a client provides a valid Unix `epoch` value (seconds since Jan 1, 1970), the `epoch` will be used instead. If the `iso8601` value is supplied it will be used instead. It's important to note, that if both a valid `epoch` and `iso8601` are supplied, the `epoch` will be used as the source of truth.
> **Timestamp Validity**: If the client provided timestamp `epoch` or `iso8601` is 10 years or more behind the service's NTP-adjusted timestamp, the client provided timestamp will be ignored as invalid resulting in a server generated timestamp.
+ Request
+ Headers
Content-Type: application/json
X-IS-AccessKey: 1234
X-IS-BucketKey: apiary_bucket
Accept-Version: ~0
+ Body
[
{
"key": "temperature",
"value": "1",
"epoch": 1419876021.778477
},
{
"key": "temperature",
"value": "2",
"epoch": 1419876022.778477
},
{
"key": "temperature",
"value": "3",
"epoch": 1419876023.778477
},
{
"key": "temperature",
"value": "4",
"epoch": 1419876024.778477
},
{
"key": "temperature",
"value": "5",
"epoch": 1419876025.778477
},
{
"key": "temperature",
"value": "6",
"epoch": 1419876026.778477
},
{
"key": "temperature",
"value": "7",
"epoch": 1419876026.778477
},
{
"key": "temperature",
"value": "8",
"epoch": 1419876027.778477
},
{
"key": "temperature",
"value": "9",
"epoch": 1419876028.778477
},
{
"key": "temperature",
"value": "10",
"epoch": 1419876029.778477
}
]
+ Response 204
+ Response 401
+ Response 402 (application/json)
+ Body
{
"message": "Event limit exceeded for current cycle..."
}
+ Response 409
+ Response 429
+ Response 500
## Events no-JSON [/events?accessKey={accessKey}&bucketKey={bucketKey}&{eventKey0}={eventValue0}&{eventKey1}={eventValue1}]
This route allows for simple URL encoded parameters that represent events. Each url key-value pair represents an event key and event value being sent to Initial State.
+ Parameters
+ accessKey (required, string, `ist_fakee8do2JQN3Eos8Ah2FS8uiFD3Ola2`) ... Access Key
+ bucketKey (required, string, `bucket1sfa`) ... Bucket Key representing bucket for the events in request
+ eventKey0 (optional, string, `eventKey0`) ... An events stream key
+ eventValue0 (optional, string, `eventValue0`) ... `eventKey0`'s value
+ eventKey1 (optional, string, `eventKey1`) ... An events stream key
+ eventValue1 (optional, string, `eventValue1`) ... `eventKey1`'s value
### Send Events [GET]
This is a break in the HTTP/1.1 spec to simplify sending events from devices without JSON serializors or full HTTP libraries with verb support. This route behaves similarly to the JSON route, but doesn't currently allow for overriding timestamps.
+ Response 204
+ Response 401
+ Response 402 (application/json)
+ Body
{
"message": "Event limit exceeded for current cycle..."
}
+ Response 409
+ Response 429
+ Response 500