-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapiary.apib
271 lines (172 loc) · 6.73 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
271
FORMAT: 1A
HOST: http://www.example.com/v2
# Location Tracker v2
Rebuild of the original Location Tracker service for Route Not Found. With, hopefully, a cleaner API.
Primary Inputs:
- Location waypoints from Tasker
- Trip information from TBD backend admin
Primary Outputs:
- Waypoint and trip data for WordPress
- Debug and stats info for TBD backend admin
Data:
- A `waypoint` is a specific geographic location with a timestamp and, optionally, geocoded information
- A `trip` is a date range and a name which collects waypoints
**This describes the API endpoint exposed by the middleware,** not the API exposed by PostgreSQL/PostgREST that the middleware uses. Trying to make both sides match got weird.
# Group Waypoints
## Create Waypoint [/waypoint]
### Create Waypoint [POST]
**I want to completely change this. This method is still v1.**
Updates should be queued client-side and submitted as a plain-text CSV file. Your API key must be submitted as a query argument; the CSV text goes in the body of the request.
There is a Tasker task template in the repository in the `/tasker` directory to do this.
HTTP Basic Authentication is required.
+ Request (text/plain)
+ Headers
Authorization: Basic basic-auth-encoded-string
+ Attributes (object)
+ date: `1-12-17` (string) - A human readable date marker; is ignored by parsing but useful for manual adjustment of queue files
+ time: `1484250000` (number) - Unix timestamp.
+ lat: `30.123` (number) - Latitude
+ lon: `-95.123` (number) - Longitude
+ Body
1-12-17,1484250000,30.123,-95.123
1-12-18,1484260000,30.456,-95.456
+ Response 201 (text/plain)
201: Record(s) created
+ Body
Location recorded.
+ Response 200 (text/plain)
200: OK
+ Body
Location received.
+ Response 400 (text/plain)
400: Could not parse input
+ Body
Bad Request: Row contained malformed coordinates
+ Response 401 (text/plain)
401: Unauthorized
+ Body
Unauthorized
### Get Recent Waypoint [GET]
Get the most recent waypoint available.
HTTP Authorization header is optional. Without it, location data will be filtered.
+ Request
+ Headers
Authorization: Basic basic-auth-encoded-string
+ Response 200 (application/json)
+ Attributes (Waypoint)
## Waypoint at Time [/waypoint/{time}]
+ Parameters
+ time (required, intiger, `1492536130`) ... A unix timestamp
### Get check-in by time [GET]
Returns a standard single waypoint object that is the closest to (earlier _or_ later) the requested time _and takes place within a trip._
HTTP Authorization header is optional. Without it, location data will be filtered.
+ Request
+ Headers
Authorization: Basic basic-auth-encoded-string
+ Response 200 (application/json)
+ Attributes (Waypoint)
+ Response 404 (application/json)
The requested timestamp was outside of any trip.
# Group Trips
Trips are manually created time-bound metadata to collect a series of Waypoints.
## Trips Index [/trips]
### Get list of Trips [GET]
Returns an array of all trip objects **without** the GeoJSON `line` property.
+ Response 200 (application/json)
+ Attributes (array[Trip])
## Create Trip [/trip]
### Create Trip [POST]
Post trip proprties to be saved to the DB. This endpoint operates as an upsert, so updates can be posted here, too. The return payload will include the trip ID.
HTTP Basic Authentication is required.
+ Request (text/plain)
+ Headers
Authorization: Basic basic-auth-encoded-string
+ Response 201 (application/json)
+ Attributes (Trip)
## Trip Details [/trip/{id}]
### Get Trip details [GET]
Get details about a particular trip, **including** the GeoJSON `line` property of coordinates within the trip's bounding timestamps.
HTTP Authorization header is optional. Without it, location data will be filtered.
+ Parameters
+ id (required, intiger, `2`) ... A trip ID
+ Request
+ Headers
Authorization: Basic basic-auth-encoded-string
+ Response 200 (application/json)
+ Attributes (Trip)
+ Response 404 (text/plain)
+ Body
Not Found: Trip ID not found
# Group History
## Full History [/history]
### Full history as a line [GET /history/line]
**For a `line` request:** A GeoJSON `LineString`. The coordinates array may be very long. All rows will be returned.
+ Request
+ Parameters
+ type: line
+ Response 200 (application/json)
+ Body
{
"type": "LineString",
"properties": {
"stroke": "#FF6633",
"stroke-width": 2
},
"coordinates": [
[
-97.740,
30.275
],
[
-97.740,
30.275
]
]
}
### Full history as a collection of Points [GET]
**For a `points` request:** A GeoJSON collection of `Features`, each of which is a `Point`. All rows will be returned.
+ Response 200 (application/json)
+ Body
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-97.740,
30.275
]
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-97.740,
30.275
]
}
}
]
}
# Group Stats
_TBD_
# Data Structures
## Waypoint (object)
+ timestamp: `1484697627` (number) - Unix timestamp
+ lon: `-97.740` (number) - Longitude
+ lat: `30.275` (number) - Latitude
+ label: `Austin, TX` (string) - Geocoded city, or greatest specificity available, if any
+ state: `Texas` (string) - State/province, if any
+ country: `United States` (string) - Country, if geocoded
+ trips (array[number]) - Array of trip IDs containing this Waypoint
## Trip (object)
+ id: `1` (number) - Trip ID
+ label: `Pacific Coast Roadtrip` (string) - Presentable trip title
+ slug: `pacific_coast_roadtrip` (string) - Slugified trip title
+ start: `1440783004` (number) - Unix timestamp for trip start
+ end: `1442329222` (number) - Unix timestamp for trip end
+ line (object) - GeoJSON trip line