|
|
This document is a complement to the official API documentation found [here](https://databasesapi.sfb.uit.no/docs/api) (or [here](https://databasesapi-test.sfb.uit.no/docs/api for the beta version).
|
|
|
This document is a complement to the official API documentation found [here](https://databasesapi.sfb.uit.no/docs/api) (or use the latest [beta version](https://databasesapi-test.sfb.uit.no/docs/api)).
|
|
|
Its purpose is to give more details about a route, or to give some illustrative examples.
|
|
|
|
|
|
## Generalities
|
... | ... | @@ -46,7 +46,7 @@ The RPC API returns JSON format. |
|
|
- Clients should send all requests with header `Content-Type: application/json`. unless a `format` option is provided.
|
|
|
- Server must send all responses with header `Content-Type: application/json.
|
|
|
|
|
|
## Records API complement
|
|
|
## Records API complements
|
|
|
|
|
|
[Official description](https://databasesapi-test.sfb.uit.no/docs/swagger-ui/index.html?url=/assets/swagger.json#/Records/get_rest_v1__dbName__records).
|
|
|
|
... | ... | @@ -111,3 +111,91 @@ The following formats may be supported by some routes: |
|
|
- `jsonld`: JSONLD
|
|
|
|
|
|
Example: [rest/v1/test/records?format=tsv&inline=true](https://databasesapi-test.sfb.uit.no/rest/v1/xxl/records?format=tsv&inline=true)
|
|
|
|
|
|
## Graphs route complements
|
|
|
|
|
|
The Graph API let third parties easily retrieve a key-values map to build graphs.
|
|
|
|
|
|
Graphs are constructed by:
|
|
|
- filtering the whole data space using the user's `filter`
|
|
|
- applying a user-defined grouping function on an attribute `x` (such as grouping records by date)
|
|
|
- for each group, one or several user-defined reduce functions are applied (such as computing the sum, max, average) on one or several attributes. Each reduce function is given by the user a label starting with `y_`.
|
|
|
- the resulting data is sorted using the user-defined sorting query,
|
|
|
- finally, the output is sent back to the user as a JSON file such as:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"graph": [
|
|
|
{
|
|
|
"x": "2020-04",
|
|
|
"y_count": 544,
|
|
|
"y_avg": 56.89
|
|
|
},
|
|
|
{
|
|
|
"x": "2020-05",
|
|
|
"y_count": 27000,
|
|
|
"y_avg": 28.02
|
|
|
},
|
|
|
...
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
The file above may have been created by the following request: [rpc/v1/test/graphs?x\[sampl:collection_date\]=mts&y_count=count&y_avg\[host:age\]=avg](https://databasesapi-test.sfb.uit.no/rpc/v1/xxl/graphs?x[sampl:collection_date]=mts&y_count=count&y_avg[host:age]=avg).
|
|
|
|
|
|
In case the grouping function is `reduce`, only one data point will be returned and have the value `null` for `x` like so:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"graph": [
|
|
|
{
|
|
|
"x": null,
|
|
|
"y_count": 27544,
|
|
|
"y_avg": 43.90
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
The file above may have been created by the following request: [rpc/v1/test/graphs?x=reduce&y_count=count&y_avg[host:age]=avg](https://databasesapi-test.sfb.uit.no/rpc/v1/xxl/graphs?x=reduce&y_count=count&y_avg[host:age]=avg).
|
|
|
|
|
|
|
|
|
#### Building a graph request
|
|
|
|
|
|
`<dbName>/graphs?ver=<version>&x[<attribute>]=<xType>&y_<key>[<attribute>]=<yType>&y_...&filter=...&sort=...`
|
|
|
|
|
|
where:
|
|
|
- `version` is the data version to query. When not provided, the latest version is used
|
|
|
- `attribute` is an attribute name (loc:country)
|
|
|
- `xType` is the method used to produce X values. One of:
|
|
|
- `each`: Each distinct values
|
|
|
- `eachR`: Distinct values (CIRIs are not expressed)
|
|
|
- `dts`: Daily time series
|
|
|
- `mts`: Monthly time series
|
|
|
- `yts`: Yearly timeseries
|
|
|
- `reduce`: Returns only one value `null`. Used to map-reduce data. `reduce` does not require any `attribute`.
|
|
|
- `key`: A name for the Y axis (must start with `y_`)
|
|
|
- `yType`: Type for the Y axis. One of:
|
|
|
- `avg`: Average
|
|
|
- `max`: Maximum
|
|
|
- `min`: Minimum
|
|
|
- `sum`: Sum
|
|
|
- `sumP`: Sum expressed as percent of the total sum
|
|
|
- `sumC`: Cumulative sum
|
|
|
- `count`: Count. Special case: `count` does not require any `attribute`.
|
|
|
- `countP`: Count expressed as percent of the total count
|
|
|
- `countC`: Cumulative count
|
|
|
- `set`: Returns a set of all unique values taken by this attribute in the group.
|
|
|
- `setR`: Raw set (CIRIs are not expressed)
|
|
|
- `filter`: See REST API
|
|
|
- `sort`: See REST API
|
|
|
|
|
|
##### Sorting
|
|
|
|
|
|
By default the data points are sorted using ascending `x`. But it is possible to sort using any of the `y_` instead. Prefix with `-` for descending ordering.
|
|
|
|
|
|
Example: [rpc/v1/test/graphs?sort=-y_count&...](https://databasesapi-test.sfb.uit.no/rpc/v1/xxl/graphs?sort=-y_count&x[sampl:collection_date]=mts&y_count=count&y_avg[host:age]=avg)
|
|
|
|
|
|
#### Limitations
|
|
|
|
|
|
- One attribute may have multiple statements. As a first draft, this API only take the first element. It could be possible to flatten all the elements on `x` (although it would be a bit tricky to implement), but it would be impossible to flatten the `y_`s due to combinational issue that would imply.
|
|
|
- Sorting will work in general, but not with `set`, `setR` and `each`. |