From 793f2a75b3062081eba254e378f08a388a581c25 Mon Sep 17 00:00:00 2001 From: Alex Jordan Date: Tue, 16 Aug 2016 19:06:35 -0400 Subject: [PATCH] Split out API docs into API.md --- API.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 104 +----------------------------------------------------- 2 files changed, 93 insertions(+), 103 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..592b989 --- /dev/null +++ b/API.md @@ -0,0 +1,92 @@ +# API + +The Recorder's API provides most of the functions that are surfaced by _ocat_. GET and POST requests are supported, and if a username and device are needed, these can be passed in via `X-Limit-User` and `X-Limit-Device` headers alternatively to GET or POST parameters. (From and To dates may also be specified as `X-Limit-From` and `X-Limit-To` respectively.) + +The API endpoint is at `/api/0` and is followed by the verb. + +## `monitor` + +Returns the content of the `monitor` file as plain text. + +``` +curl 'http://127.0.0.1:8083/api/0/monitor' +1441962082 owntracks/jjolie/phone +``` + +## `last` + +Returns a list of last users' positions. (Can be limited by _user_, _device_, and _fields_, a comma-separated list of fields which should be returned instead of the default of all fields.) + +``` +curl http://127.0.0.1:8083/api/0/last [-d user=jjolie [-d device=phone]] +``` + +``` +curl 'http://127.0.0.1:8083/api/0/last?fields=tst,tid,addr,topic,isotst' +``` + +## `list` + +List users. If _user_ is specified, lists that user's devices. If both _user_ and _device_ are specified, lists that device's `.rec` files. + +## `locations` + +Here comes the actual data. This lists users' locations and requires both _user_ and _device_. Output format is JSON unless a different _format_ is given (`csv`, `json`, `geojson`, `xml`, and `linestring` are supported). + +In order to limit the number of records returned, use _limit_ which causes a reverse search through the `.rec` files; this can be used to find the last N positions. + +Date/time ranges may be specified as _from_ and _to_ with dates/times specified as described for _ocat_ above. + +``` +curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s +curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s -d limit=1 +curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s -d format=geojson +curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s -d from=2014-08-03 +curl 'http://127.0.0.1:8083/api/0/locations?from=2015-09-01&user=jpm&device=5s&fields=tst,tid,addr,isotst' +``` + +## `q` + +Query the geo cache for a particular _lat_ and _lon_. + +``` +curl 'http://127.0.0.1:8083/api/0/q?lat=48.85833&lon=2.295' +{ + "cc": "FR", + "addr": "9 Avenue Anatole France, 75007 Paris, France", + "tst": 1441984405 +} +``` + +The reported timestamp was the time at which this cache entry was made. Note that this interface queries only -- it does not populate the cache. + +## `photo` + +Requires GET method and _user_, and will return the `image/png` 40x40px photograph of a user if available in `STORAGEDIR/photos/` or a transparent 40x40png with a black border otherwise. + +## `kill` + +If support for this is compiled in, this API endpoint allows a client to remove data from _storage_. (Warning: *any* client can do this, as there is no authentication/authorization in the Recorder!) + +``` +curl 'http://127.0.0.1:8083/api/0/kill?user=ngin&device=ojo' + +{ + "path": "s0/rec/ngin/ojo", + "status": "OK", + "last": "s0/last/ngin/ojo/ngin-ojo.json", + "killed": [ + "2015-09.rec", + ] +} +``` +The response contains a list of removed `.rec` files, and file system operations are logged to syslog. + +## `version` + +Returns a JSON object which contains the Recorder's version string, such as + +```json +{ "version": "0.4.7" } +``` + diff --git a/README.md b/README.md index 4b16c7c..97fc190 100644 --- a/README.md +++ b/README.md @@ -31,15 +31,6 @@ We developed the Recorder as a one-stop solution to storing location data publis * [Display a track (a.k.a. linestring)](#display-a-track-aka-linestring) * [Tabular display](#tabular-display) * [Live map](#live-map) - * [API](#api) - * [`monitor`](#monitor) - * [`last`](#last) - * [`list`](#list) - * [`locations`](#locations) - * [`q`](#q) - * [`photo`](#photo) - * [`kill`](#kill) - * [`version`](#version) * [`ocat`](#ocat) * [Environment](#environment) * [Examples](#examples) @@ -272,7 +263,7 @@ This section lists the most important options of the Recorder with their long na The Recorder has a built-in HTTP server with which it servers static files from either the compiled-in default `DOCROOT` directory or that specified at run-time with the `--doc-root` option. Furthermore, it serves JSON data from the API end-point at `/api/0/` and it has a built-in WebSocket server for the live map. -The API basically serves the same data as _ocat_ is able to produce. The server also accepts OwnTracks app data via HTTP POST to the `/pub` endpoint. +The API basically serves the same data as _ocat_ is able to produce - see [API.md](https://github.com/owntracks/recorder/blob/master/API.md). The server also accepts OwnTracks app data via HTTP POST to the `/pub` endpoint. ### Example functionality @@ -348,99 +339,6 @@ The Recorder's built-in WebSocket server updates a map as it receives publishes ![Live map](assets/demo-live-map.png) -### API - -The Recorder's API provides most of the functions that are surfaced by _ocat_. GET and POST requests are supported, and if a username and device are needed, these can be passed in via `X-Limit-User` and `X-Limit-Device` headers alternatively to GET or POST parameters. (From and To dates may also be specified as `X-Limit-From` and `X-Limit-To` -respectively.) - -The API endpoint is at `/api/0` and is followed by the verb. - -#### `monitor` - -Returns the content of the `monitor` file as plain text. - -``` -curl 'http://127.0.0.1:8083/api/0/monitor' -1441962082 owntracks/jjolie/phone -``` - -#### `last` - -Returns a list of last users' positions. (Can be limited by _user_, _device_, and _fields_, a comma-separated list of fields which should be returned instead of the default of all fields.) - -``` -curl http://127.0.0.1:8083/api/0/last [-d user=jjolie [-d device=phone]] -``` - -``` -curl 'http://127.0.0.1:8083/api/0/last?fields=tst,tid,addr,topic,isotst' -``` - -#### `list` - -List users. If _user_ is specified, lists that user's devices. If both _user_ and _device_ are specified, lists that device's `.rec` files. - -#### `locations` - -Here comes the actual data. This lists users' locations and requires both _user_ and _device_. Output format is JSON unless a different _format_ is given (`csv`, `json`, `geojson`, `xml`, and `linestring` are supported). - -In order to limit the number of records returned, use _limit_ which causes a reverse search through the `.rec` files; this can be used to find the last N positions. - -Date/time ranges may be specified as _from_ and _to_ with dates/times specified as described for _ocat_ above. - -``` -curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s -curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s -d limit=1 -curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s -d format=geojson -curl http://127.0.0.1:8083/api/0/locations -d user=jpm -d device=5s -d from=2014-08-03 -curl 'http://127.0.0.1:8083/api/0/locations?from=2015-09-01&user=jpm&device=5s&fields=tst,tid,addr,isotst' -``` - -#### `q` - -Query the geo cache for a particular _lat_ and _lon_. - -``` -curl 'http://127.0.0.1:8083/api/0/q?lat=48.85833&lon=2.295' -{ - "cc": "FR", - "addr": "9 Avenue Anatole France, 75007 Paris, France", - "tst": 1441984405 -} -``` - -The reported timestamp was the time at which this cache entry was made. Note that this interface queries only -- it does not populate the cache. - -#### `photo` - -Requires GET method and _user_, and will return the `image/png` 40x40px photograph of a user if available in `STORAGEDIR/photos/` or a transparent 40x40png with a black border otherwise. - -#### `kill` - -If support for this is compiled in, this API endpoint allows a client to remove data from _storage_. (Warning: *any* client can do this, as there is no authentication/authorization in the Recorder!) - -``` -curl 'http://127.0.0.1:8083/api/0/kill?user=ngin&device=ojo' - -{ - "path": "s0/rec/ngin/ojo", - "status": "OK", - "last": "s0/last/ngin/ojo/ngin-ojo.json", - "killed": [ - "2015-09.rec", - ] -} -``` -The response contains a list of removed `.rec` files, and file system operations are logged to syslog. - -#### `version` - -Returns a JSON object which contains the Recorder's version string, such as - -```json -{ "version": "0.4.7" } -``` - ## `ocat` _ocat_ is a CLI query program for data stored by Recorder: it prints data from storage in a variety of output formats: