Project

General

Profile

APIs » History » Version 4

Philippe May, 05/04/2021 11:56

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 4 Philippe May
* where: JSON compliant string specifying the id of the feature (eg. @{"avsm_misc.weather_station":4}@)
39 4 Philippe May
40 4 Philippe May
Optional:
41 4 Philippe May
42 4 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:15m@ for 15 minutes intervals) 
43 4 Philippe May
44 4 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@)
45 4 Philippe May
46 4 Philippe May
47 4 Philippe May
h4. Real life example: gather historical weather station data
48 4 Philippe May
49 4 Philippe May
In the following scenario, a third party needs to get the time series of the temperatures recorded by weather stations.
50 4 Philippe May
51 4 Philippe May
Different weather stations send data to different cloud based services, using different conventions (field names, units, etc). Yet, Gisaf collects in near real-time the data from the different service providers and its API can be used to unify the access across all the providers.