Version: 2.0.2

Getting started

CIVITAS/CORE has two types of API:

The Portal Backend API manages the platform, for example datasets, data sources and permissions.
The Dataset Payload APIs give access to the data of a published dataset.

Both APIs need a Bearer token. The Authentication page explains how to get a token.

Prerequisites

A user account with a password with <username> and <password>
<your-domain>: if the portal is at https://portal.example.org, it is example.org
<realm>: the part after /realms/ in the URL of the sign-in page, for example staging in https://idm.example.org/realms/staging/...
curl and jq

Quick tour

1. Get a token

Save the token in the TOKEN variable:

TOKEN=$(curl --silent --request POST \
  "https://idm.<your-domain>/realms/<realm>/protocol/openid-connect/token" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=api-access" \
  --data-urlencode "username=<username>" \
  --data-urlencode "password=<password>" \
  | jq -r .access_token)

If the user has TOTP configured, also add --data-urlencode "otp=<six-digits>". If $TOKEN is null, the request failed. Run the command without | jq -r .access_token to see the error.

More: Authentication.

2. Check the token

curl "https://management.<your-domain>/v1/users/me" \
  --header "Authorization: Bearer $TOKEN"

The response shows your user.

3. Find a dataset ID

Open the dataset in the portal. The ID is the last part of the URL. In https://portal.example.org/datasets/c7a53af9-e78d-4351-b473-8116531bf74c, the ID is c7a53af9-e78d-4351-b473-8116531bf74c.

DATASET_ID=<dataset-id>

4. List the APIs of the dataset

curl "https://management.<your-domain>/v1/datasets/$DATASET_ID/apis" \
  --header "Authorization: Bearer $TOKEN"

The list is empty if the dataset does not have the status AVAILABLE. Save the URL of the first API:

PREVIEW_URL=$(curl --silent \
  "https://management.<your-domain>/v1/datasets/$DATASET_ID/apis" \
  --header "Authorization: Bearer $TOKEN" \
  | jq -r '.[0].previewUrl')

More: Discover the published APIs.

5. Get data

For an STA API:

curl "$PREVIEW_URL/Things" \
  --header "Authorization: Bearer $TOKEN"

For an OWS API:

curl "$PREVIEW_URL?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetCapabilities" \
  --header "Authorization: Bearer $TOKEN"

More: OWS Payload API and STA Payload API.

Prerequisites​

Quick tour​

1. Get a token​

2. Check the token​

3. Find a dataset ID​

4. List the APIs of the dataset​

5. Get data​