Project

General

Profile

APIs » History » Version 7

Philippe May, 05/04/2021 12:19

1 1 Philippe May
h1. APIs
2 1 Philippe May
3 1 Philippe May
Gisaf's web interface uses server's APIs, that can also be used for third party software integration, eg. for retrieving data from the database with HTTP requests.
4 1 Philippe May
5 1 Philippe May
The APIs use 2 technologies: json REST stores and Graphql.
6 1 Philippe May
7 2 Philippe May
This page is a work-in-progress documentation effort. Refer to source code for a comprehensive and up to date API list and usage:
8 1 Philippe May
9 1 Philippe May
* https://redmine.auroville.org.in/projects/gisaf/repository/revisions/master/entry/gisaf/api.py
10 1 Philippe May
* https://redmine.auroville.org.in/projects/gisaf/repository/revisions/master/entry/gisaf/graphql_api.py
11 1 Philippe May
12 2 Philippe May
It's also easy to track the HTTP requests in use by the web site, using standard web development tools like those embedded in all modern browsers.
13 2 Philippe May
14 2 Philippe May
15 1 Philippe May
h2. Json stores
16 1 Philippe May
17 1 Philippe May
h3. Getting record values from devices
18 1 Philippe May
19 1 Philippe May
For the custom models that define time-based values, eg. fetched from "IoT" enabled devices such as weather stations or other sensors, the generic HTTP request scheme is:
20 1 Philippe May
21 1 Philippe May
<pre>
22 2 Philippe May
<http_request_prefix>/api/<store>/values/<value>?<parameters>
23 1 Philippe May
</pre>
24 2 Philippe May
25 2 Philippe May
Where:
26 2 Philippe May
27 3 Philippe May
* http_request_prefix: base URI base of the site (eg. @https://gis.auroville.org.in@)
28 3 Philippe May
* store: name of the store of the geographical feature (eg. @avsm_misc.weather_station@)
29 3 Philippe May
* value: name of the value for the store (eg. @temperature@)
30 1 Philippe May
* parameters: URL-encoded query string, see below for details.
31 1 Philippe May
32 1 Philippe May
h4. Parameters
33 3 Philippe May
34 4 Philippe May
The parameters must be formatted with a URI-compliant query syntax. Note that the URI encoding isn't required
35 3 Philippe May
36 3 Philippe May
Required:
37 1 Philippe May
38 5 Philippe May
* where: JSON compliant string specifying the id of the feature (eg. @where={"avsm_misc.weather_station":4}@)
39 4 Philippe May
40 4 Philippe May
Optional:
41 4 Philippe May
42 5 Philippe May
* resample: plain text resampling time interval for Pandas, see https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#dateoffset-objects for a complete description (eg. @resample=D@ for day, @resample:15min@ for 15 minutes intervals) 
43 1 Philippe May
44 5 Philippe May
* sort: JSON compliant string specifying the value to sort on, with a boolean for the sort order (true for ascending, false for descending) (eg. @time=true@). If @resample@ is given, the returned series is  
45 1 Philippe May
46 5 Philippe May
h4. Output
47 1 Philippe May
48 5 Philippe May
The output is a json string: an array of data points with key-value pairs of the requested values.
49 5 Philippe May
50 1 Philippe May
h4. Real life example: gather historical weather station data
51 1 Philippe May
52 6 Philippe May
In the following scenario, a third party needs to get the time series of the temperatures recorded by weather stations for data analytics coupled with other inputs.
53 1 Philippe May
54 6 Philippe May
Different weather stations send data to different cloud based services, using different conventions (field names, units, etc) and eventually access permissions. Luckily, Gisaf collects in near real-time data from the different service providers, and its API can be used to unify the access of these data across all the devices in a consistent way, independent from the device models and service providers.
55 6 Philippe May
56 7 Philippe May
In this example, the standard command utility @curl@ is used; the URL used as argument can be used by any HTTP client, including directly in web browsers or with programming language libraries for automation.
57 6 Philippe May
58 6 Philippe May
The command is like:
59 6 Philippe May
60 6 Philippe May
<pre>
61 6 Philippe May
curl 'https://gis.auroville.org.in/api/avsm_misc.weather_station/values/temperature?where={"avsm_misc.weather_station":4}&time=false&resample=m'
62 6 Philippe May
</pre>
63 6 Philippe May
64 6 Philippe May
Where:
65 6 Philippe May
66 6 Philippe May
* The Auroville Gisaf public server is used
67 6 Philippe May
* The store for weather stations is @avsm_misc.weather_station@
68 6 Philippe May
* The id of the weather station is 4. The list of weather stations can be found at https://gis.auroville.org.in/measures/avsm_misc.weather_station
69 6 Philippe May
* The value to be fetched is @temperature@. The list of the available values can be found at https://gis.auroville.org.in/measures/avsm_misc.weather_station/4
70 6 Philippe May
* The resample base is 1 month. Other valid resampling interval include:
71 6 Philippe May
 * @h@ or @1h@: 1 hour
72 6 Philippe May
 * @15m@: 15 minutes
73 6 Philippe May
 * @d@ or @1d@: 1 day
74 6 Philippe May
 * @2w@: 2 weeks