Skip to content
This repository has been archived by the owner on Mar 14, 2024. It is now read-only.

Aam-Digital/query-backend

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Feb 9, 2024
b916388 · Feb 9, 2024

History

11 Commits
Nov 28, 2023
Dec 16, 2023
Feb 9, 2024
Dec 16, 2023
Nov 28, 2023
Dec 16, 2023
Nov 28, 2023
Nov 28, 2023
Nov 28, 2023
Nov 28, 2023
Feb 9, 2024
Dec 16, 2023
Nov 28, 2023
Nov 28, 2023
Nov 28, 2023
Nov 28, 2023

Repository files navigation

Query Backend

This service allows to run SQL queries on the database. In particular, this service allows users with limited permissions to see reports of aggregated statistics across all data (e.g. a supervisor could analyse reports without having access to possibly confidential details of participants or notes).

Deployment

See the ndb-setup repo for full deployment instructions.

To use this you need a running CouchDB and structured query server (SQS).

The following variables might need to be configured in the .env file:

  • DATABASE_URL URL of the CouchDB or replication backend
  • QUERY_URL URL of the SQS
  • SCHEMA_CONFIG_ID database ID of the document which holds the SQS schema (default _design/sqlite:config)
  • PORT where the app should listen (default 3000)
  • SENTRY_DSN for remote logging

API access to reports

Reports and their results are available for external services through the given API endpoints (see OpenAPI specs). Endpoints require a valid JWT access token, which can be fetched via OAuth2 client credential flow.

Initial setup of an API integration

  1. Request client_id and client_secret from server administrator (--> admin has to create new client grant in Keycloak)

Keycloak Client Setup

  1. Get the realm of your instance (e.g. https://[your_realm].aam-digital.com). This is both the subdomain of systems hosted on aam-digital.com and the Keycloak Realm for authentication (case sensitive!).

Access a report via API (after setup)

  1. Get valid access token using your client secret:
curl -X "POST" "https://keycloak.aam-digital.net/realms/<your_realm>/protocol/openid-connect/token" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "client_id=<your_client_id>" \
     --data-urlencode "client_secret=<your_client_secret>" \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "scopes=openid reports_read reports_write"

Check API docs for the required "scopes". This returns a JWT access token required to provided as Bearer Token for any request to the API endpoints. Sample token:

{
  "access_token": "eyJhbGciOiJSUzI...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "openid reports_read reports_write"
}
  1. Request the all available reports: GET /reports (see OpenAPI specs for details)
  2. Trigger the calculation of a reports data: POST /report-calculation/<report-id>
  3. Get status of the report calculation: GET /report-calculation/<calculation-id>
  4. Once the status shows the calculation is completed, get the actual result data: GET /report-calculation/<calculation-id>/data

Subscribe to continous changes of a report

  1. Create an initial webhook (if not already registered): POST /webhook
  2. Register for events of the selected report: POST /webhook/{webhookId}/subscribe/report/{reportId}:
  3. You will receive Event objects to your webhook, including an initial event directly after you subscribe, pointing to the current report data
  4. Use the report-calculation-id in the event to fetch actual data from /report-calculation endpoint

About

Service that allows to query the database

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages