... | @@ -19,14 +19,9 @@ The REST API endpoints can be queried using standard HTTP methods, primarily ~GE |
... | @@ -19,14 +19,9 @@ The REST API endpoints can be queried using standard HTTP methods, primarily ~GE |
|
When using the [[https://curl.se/][curl]] tool, this translates to the following command:
|
|
When using the [[https://curl.se/][curl]] tool, this translates to the following command:
|
|
|
|
|
|
#+begin_src sh :results output :export both
|
|
#+begin_src sh :results output :export both
|
|
curl -s -X GET "https://stats.adam.nic.cz:443/fred_domains?limit=3"
|
|
curl -X GET "https://stats.adam.nic.cz:443/fred_domains"
|
|
#+end_src
|
|
#+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.
|
|
Queries can be modified via query string parameters. A selection of important parameters is given below.
|
|
|
|
|
|
** Limits and pagination
|
|
** Limits and pagination
|
... | @@ -44,6 +39,41 @@ For example, the following query results in 3 records from ~/fred_domains~ to be |
... | @@ -44,6 +39,41 @@ For example, the following query results in 3 records from ~/fred_domains~ to be |
|
|
|
|
|
** Record filtering
|
|
** Record filtering
|
|
|
|
|
|
Apart from specifying ~limit~ and ~offset~, it is also possible to filter returned records based on specified properties
|
|
Apart from specifying ~limit~ and ~offset~, it is also possible to filter returned records based on specified properties that have to be specified in query parameters using a special syntax. For example, to get results from ~/fred_domains~ only for *cz* zone, one can use the query
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
GET /fred_domains?zone=eq.cz HTTP/1.1
|
|
|
|
#+end_example
|
|
|
|
|
|
|
|
PostgREST provides a number of filtering operators, the most common are listed in the following table:
|
|
|
|
|
|
|
|
| Operator | Meaning |
|
|
|
|
|----------+-----------------------|
|
|
|
|
| ~neq~ | equals |
|
|
|
|
| ~neq~ | not equal |
|
|
|
|
| ~gt~ | greater than |
|
|
|
|
| ~gte~ | greater than or equal |
|
|
|
|
| ~lt~ | less than |
|
|
|
|
| ~lte~ | less than or equal |
|
|
|
|
|
|
|
|
Assume we want to further restrict the previous query and show only records with the number of domains at least 1.36 million. This query does the job:
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
GET /fred_domains?zone=eq.cz&domains=gte.1360000 HTTP/1.1
|
|
|
|
#+end_example
|
|
|
|
|
|
|
|
** Member filtering
|
|
|
|
|
|
|
|
It is also possible to select returned record members that correspond to columns in database tables. This is done using the ~select~ query parameter. For example, let's say we are interested in receiving only the ~domains~ and ~zone~ members in ~/fred_domains~ records:
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
GET /fred_domains?select=domains,zone HTTP/1.1
|
|
|
|
#+end_example
|
|
|
|
|
|
* OpenAPI/Swagger
|
|
* OpenAPI/Swagger
|
|
|
|
|
|
|
|
PostgREST also generates a description of the REST API using the [[https://swagger.io/specification][OpenAPI]] language. It is served from the [[https://stats.adam.nic.cz][root endpoint]].
|
|
|
|
|
|
|
|
A more attractive representation of the OpenAPI specification is the so-called Swagger UI, available from https://stats.adam.nic.cz/swagger. This web interface lists all available endpoints and available query parameters.
|
|
|
|
|
|
|
|
REST API queries can also be executed directly from the Swagger UI. To do so, click on an endpoint and then on the *Try it out*. After specifying parameters in the web form, the query can be run using the *Execute* bar. To avoid excessively long responses, it is recommended to set at least the ~limit~ parameter to a reasonable number. |