|
|
All tables in the PostgreSQL database that serve as a basis for generating most graphs and statistics are also available via REST API. This is a convenient interface for machine access and independent use of the data.
|
|
|
|
|
|
The REST API is generated automatically using the powerful [[http://postgrest.org][PostgREST]] API server. This tools exposes all database tables and views in a flat set of /API endpoints/ – all routes are just one-level deep.
|
|
|
|
|
|
The root endpoint of CZ.NIC statistics is https://stats.adam.nic.cz.
|
|
|
|
|
|
Some endpoints are protected and require authenticated access. See [[API-Tokens]] for details.
|
|
|
|
|
|
* Querying the API
|
|
|
|
|
|
In order to fully utilize the potential of the REST API generated by PostgREST, it is recommended to read the [[http://postgrest.org/en/v7.0.0/api.html][documentation]]. The following paragraphs contain only basic instructions.
|
|
|
|
|
|
The REST API endpoints can be queried using standard HTTP methods, primarily ~GET~ but also ~HEAD~ and ~OPTIONS~. For example, complete data from the ~/fred_domains~ endpoint can be obtained in the response to
|
|
|
|
|
|
#+begin_example
|
|
|
GET /fred_domains HTTP/1.1
|
|
|
#+end_example
|
|
|
|
|
|
When using the [[https://curl.se/][curl]] tool, this translates to the following command:
|
|
|
|
|
|
#+begin_src shell :results output
|
|
|
curl -X GET "https://stats.adam.nic.cz:443/fred_domains?limit=3"
|
|
|
#+end_src
|
|
|
|
|
|
#+RESULTS:
|
|
|
: [{"ts":"2020-05-22T12:00:00+00:00","domains":177,"zone":"0.2.4.e164.arpa"},
|
|
|
: {"ts":"2020-05-22T12:00:00+00:00","domains":1359991,"zone":"cz"},
|
|
|
: {"ts":"2019-12-31T23:59:59+00:00","domains":176,"zone":"0.2.4.e164.arpa"}]
|
|
|
|
|
|
Queries can be modified via query string parameters. A selection of important parameters is given below.
|
|
|
|
|
|
** Limits and pagination
|
|
|
|
|
|
Some queries may return large volumes of data. For example, the above query to ~/fred_domains~, which is still relatively moderate, returns currently 378 records. The extent of returned records can be controlled using the following query parameters:
|
|
|
|
|
|
- limit :: Set the maximum number of records to be returned
|
|
|
- offset :: Index of the first record to be returned (starting from 0)
|
|
|
|
|
|
For example, the following query results in 3 records from ~/fred_domains~ to be returned, starting from record #1 (second in the sequence):
|
|
|
|
|
|
#+begin_example
|
|
|
GET /fred_domains?limits=3&offset=1 HTTP/1.1
|
|
|
#+end_example
|
|
|
|
|
|
* OpenAPI/Swagger |