Developers

ALISE JSON API v2

AGLAIA is the API server of the ALISE platform. Its JSON API lets applications log in users, read ontologies and their specifications, and create, find, change and share Siles: the semantic objects of LETO, described by categories, attributes and Slinks (semantic links).

Base URLhttps://<your-aglaia-server>/api

Overview

Base URL: https://<your-aglaia-server>/api; a local AGLAIA answers on http://localhost:8080/api. Every path below starts with /v2.
Format: JSON in UTF-8, requests with Content-Type: application/json.
Authentication: endpoints marked Auth need a signed Authentication header (HMAC). Log in once, then sign every request; see Authentication.
Ontology: the Ontology header selects one of the ontologies registered in AGLAIA. Without it the server's default ontology is used. List them with GET /v2/ontology/list.
One request at a time: the nonce of each request must be higher than the one before, so send the requests of a session one after another, not in parallel.
HTTP/1.1: AGLAIA does not answer HTTP/2 upgrade requests; clients that try HTTP/2 first (like Java's HttpClient) must be set to HTTP/1.1.

Authentication

Requests are authorised with HMAC (hash based message authentication):

POST /v2/login with e-mail and password returns a secret. It is valid for this app until GET /v2/logout.
Every further request carries the header
```
Authentication: hmac <user>:<nonce>:<digest>
digest = hex(sha256(secret + METHOD + path + nonce))
```
- user: the e-mail used to log in
- METHOD: the HTTP method in capitals, e.g. POST
- path: the request path without /api and with the query string, e.g. /v2/sile/filter?content=label&limit=10. Signing without the query is rejected.
- nonce: a number that grows with every request of the session (1, 2, 3 …).

AGLAIA looks up the session secrets of the user, keeps only those of the requesting app (host), checks that the nonce is higher than the last one seen, rebuilds the digest and compares it. Otherwise it answers 401 Invalid Authorization Header.

A complete request then looks like this:

POST /api/v2/sile/filter?content=label&limit=10 HTTP/1.1
Host: localhost:8080
Authentication: hmac user@example.com:3:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
Ontology: http://library.alise.systems/ontology/polis#
Content-Type: application/json

[ { "type": "category", "label": "Application" } ]

The code on the right is a small, complete client for each language: copy it once, then use the samples of the endpoints below. For curl, run the lines in a bash shell (Linux, macOS, Git Bash); on macOS use shasum -a 256 instead of sha256sum.

# your AGLAIA server, ontology and account
ALISE_API='http://localhost:8080/api'
ALISE_ONTOLOGY='http://library.alise.systems/ontology/polis#'
ALISE_USER='you@example.com'
ALISE_PASSWORD='your password'

# log in: keep the secret, start counting nonces
ALISE_SECRET=$(curl -s -X POST "$ALISE_API/v2/login" \
  -H 'Content-Type: application/json' \
  -d "{\"email\": \"$ALISE_USER\", \"password\": \"$ALISE_PASSWORD\"}" \
  | sed -E 's/.*"secret" *: *"([^"]+)".*/\1/')
ALISE_NONCE=0

# sign and send one request (the samples below do exactly this)
P='/v2/sile/filter?content=label&limit=10'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '[{"type": "null"}]'

// ALISE JSON API v2 client: Node.js 18+ or a page served by the AGLAIA host
class Aglaia {
  constructor(api, ontology) {
    this.api = api.replace(/\/$/, '');
    this.ontology = ontology;
    this.nonce = 0;
  }

  async login(email, password) {
    const session = await this.request('POST', '/v2/login', { email, password }, { signed: false });
    this.user = email;
    this.secret = session.secret;
    this.nonce = 0;
    return session;
  }

  /** path starts with /v2 and includes the query string */
  async request(method, path, body, { signed = true } = {}) {
    const headers = { 'Content-Type': 'application/json', Accept: 'application/json' };
    if (this.ontology) headers.Ontology = this.ontology;
    if (signed) {
      this.nonce += 1;
      const digest = await sha256(this.secret + method + path + this.nonce);
      headers.Authentication = `hmac ${this.user}:${this.nonce}:${digest}`;
    }
    const response = await fetch(this.api + path, {
      method, headers, body: body === undefined ? undefined : JSON.stringify(body),
    });
    const text = await response.text();
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
    return text ? JSON.parse(text) : null;
  }

  logout() {
    return this.request('GET', '/v2/logout');
  }
}

async function sha256(text) {
  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
  return Array.from(new Uint8Array(hash), b => b.toString(16).padStart(2, '0')).join('');
}

// your AGLAIA server, ontology and account
const aglaia = new Aglaia('http://localhost:8080/api', 'http://library.alise.systems/ontology/polis#');
await aglaia.login('you@example.com', 'your password');

# ALISE JSON API v2 client (pip install requests)
import hashlib

import requests


class Aglaia:
    def __init__(self, api, ontology=None):
        self.api = api.rstrip("/")
        self.ontology = ontology
        self.user = self.secret = None
        self.nonce = 0

    def login(self, email, password):
        session = self.request("POST", "/v2/login", {"email": email, "password": password}, signed=False)
        self.user, self.secret, self.nonce = email, session["secret"], 0
        return session

    def request(self, method, path, body=None, signed=True):
        """path starts with /v2 and includes the query string"""
        headers = {"Content-Type": "application/json", "Accept": "application/json"}
        if self.ontology:
            headers["Ontology"] = self.ontology
        if signed:
            self.nonce += 1
            digest = hashlib.sha256(f"{self.secret}{method}{path}{self.nonce}".encode()).hexdigest()
            headers["Authentication"] = f"hmac {self.user}:{self.nonce}:{digest}"
        response = requests.request(method, self.api + path, json=body, headers=headers, timeout=30)
        if not response.ok:
            raise RuntimeError(f"HTTP {response.status_code}: {response.text}")
        return response.json() if response.content else None

    def logout(self):
        self.request("GET", "/v2/logout")


# your AGLAIA server, ontology and account
aglaia = Aglaia("http://localhost:8080/api", ontology="http://library.alise.systems/ontology/polis#")
aglaia.login("you@example.com", "your password")

// Aglaia.java: ALISE JSON API v2 client, JDK 17+ only
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Aglaia {
    // AGLAIA does not answer HTTP/2 upgrade requests
    private final HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
    private final String api;
    private final String ontology;
    private String user;
    private String secret;
    private long nonce;

    public Aglaia(String api, String ontology) {
        this.api = api.replaceAll("/$", "");
        this.ontology = ontology;
    }

    public String login(String email, String password) throws Exception {
        String session = send("POST", "/v2/login",
                "{\"email\": " + quote(email) + ", \"password\": " + quote(password) + "}", false);
        Matcher m = Pattern.compile("\"secret\"\\s*:\\s*\"([^\"]+)\"").matcher(session);
        if (!m.find()) {
            throw new IllegalStateException("No secret in " + session);
        }
        user = email;
        secret = m.group(1);
        nonce = 0;
        return session;
    }

    /** Signed request; path starts with /v2 and includes the query string. */
    public String request(String method, String path, String json) throws Exception {
        return send(method, path, json, true);
    }

    public String send(String method, String path, String json, boolean signed) throws Exception {
        HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(api + path))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .method(method, json == null ? HttpRequest.BodyPublishers.noBody()
                        : HttpRequest.BodyPublishers.ofString(json));
        if (ontology != null) {
            request.header("Ontology", ontology);
        }
        if (signed) {
            nonce++;
            byte[] hash = MessageDigest.getInstance("SHA-256")
                    .digest((secret + method + path + nonce).getBytes(StandardCharsets.UTF_8));
            request.header("Authentication", "hmac " + user + ":" + nonce + ":" + HexFormat.of().formatHex(hash));
        }
        HttpResponse<String> response = http.send(request.build(), HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": " + response.body());
        }
        return response.body();
    }

    public void logout() throws Exception {
        request("GET", "/v2/logout", null);
    }

    private static String quote(String text) {
        return "\"" + text.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
    }
}

// usage, e.g. in main(): your AGLAIA server, ontology and account
Aglaia aglaia = new Aglaia("http://localhost:8080/api", "http://library.alise.systems/ontology/polis#");
aglaia.login("you@example.com", "your password");

Siles

Siles are the objects AGLAIA stores. A Sile is identified by its URI (e.g. urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f), has a human readable, searchable label and carries metadata: attributes (values), categories (types) and Slinks (semantic links to other Siles). It can also hold binary content, such as an image. Which categories, attributes and Slinks exist is defined by the ontology, see GET /v2/ontology/spect.

{
  "uri": "urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f",
  "label": "Notes",
  "binaryArray": "lsadf89a43q4…",
  "attributes": {
    "vendor": ["AL!SE.SYSTEMS"],
    "version": ["1.0.0"]
  },
  "categories": ["Application"],
  "slinks": {
    "dependsOn": [
      { "uri": "urn:uuid:8b6f1c2a-3d4e-4f5a-9b6c-7d8e9f0a1b2c", "label": "Hello World" }
    ]
  }
}

Attribute values are always lists of strings. Attributes and Slinks that the ontology does not define for the Sile's categories are dropped without an error.

How much is returned: every call that returns Siles takes ?content=:

`content`	Returned
`uri`	only with several Siles: a JSON array of URIs
`date`	only with several Siles: objects with `uri` and `update-date`
`label`	`uri` and `label`
`metadata`	`uri`, `label`, `attributes`, `categories` and `slinks` (default)
`binary`	`uri`, `label` and the binary data
`all`	the complete Sile

Filters

POST /v2/sile/filter, /filter/uris and /filter/count take a filter as request body: a JSON array of conditions, all of which must match. Conditions are combined with and, or and not:

[
  {
    "and": [
      {
        "or": [
          { "type": "category", "label": "Person" },
          { "type": "category", "label": "Topic" },
          { "type": "attributetypevalue", "label": "FirstName", "value": "Franz" }
        ]
      },
      { "type": "attributetyperange", "label": "AvgHeartRate", "minvalue": "80", "maxvalue": "120" }
    ]
  },
  { "not": { "type": "category", "label": "Company" } }
]

Atomic conditions (✓ = field used):

`type`	`sileuri`	`label`	`value`	`minvalue` / `maxvalue`	Matches Siles …
`null`					all Siles
`category`		✓			with this category
`labelvalue`			✓		with this label
`fulltextpattern`			✓		whose tags match this regular expression (case-insensitive)
`attributetype`		✓			with at least one attribute of this type
`attributetypevalue`		✓	✓		with this attribute type and value
`attributerange`				✓	with any attribute value in the range
`attributetyperange`		✓		✓	with this attribute type and a value in the range
`sileinbound`	✓				that link to the given Sile
`sileoutbound`	✓				that the given Sile links to
`sileinoutbound`	✓				linked to or from the given Sile
`sileslinkinbound`	✓	✓			linked by the given Sile with this Slink type
`sileslinkoutbound`	✓	✓			linking to the given Sile with this Slink type
`slinkinbound`		✓			that are the target of a Slink of this type
`slinkoutbound`		✓			that have a Slink of this type
`slinkinoutbound`		✓			with a Slink of this type in either direction

label is the short name from the ontology (Application, not the full URI).

Paging: ?limit= (default: all) and ?offset= (default 0) on /v2/sile/filter.

Errors

Errors use the HTTP status code and this JSON body:

{
  "error": {
    "code": 401,
    "message": "Invalid Authorization Header.",
    "errors": [ { "domain": "global", "message": "Invalid Authorization Header." } ]
  }
}

Status	Meaning
`401`	Missing or wrong signature, a nonce that is not higher than the last one, or a session that was logged out. Log in again.
`404`	No Sile, role or category with this id, for example `Sile not found.`
`500`	The request could not be processed, for example a body of the wrong shape or an unknown category. The `message` names the cause.

Notes

Creating and changing requests return the changed entity itself rather than its URL, which saves the client a second request.
DELETE /v2/sile/{id} marks the Sile as deleted and returns {}; it is gone for all reads. DELETE /v2/sile/squeeze removes deleted Siles for good.
/v2/sile/filter/uris, /v2/sile/filter/count and /v2/category/children/{category} currently resolve category names in the server's default ontology and ignore the Ontology header. With another ontology, use /v2/sile/filter?content=uri and count the result; read subcategories from the OWL file.
The permission endpoints correspond to the XML-RPC methods getSileRolePermissions, setSileRolePermission and checkUserSilePermission.
AGLAIA 3 has further endpoints that are not described here yet: /v2/apps, /v2/app, /v2/question, /v2/user/all, DELETE /v2/user/{id}, /v2/license/…, PATCH /v2/sile/fileupload/{id} (multipart file upload) and the customer specific /v2/oebv/… and /v2/demo/….

Source code (AGLAIA, LETO):

Component	File
REST API, Sile endpoints	`aglaia3/…/aglaia3/api/v2/Sile.java`
REST API, Role endpoints	`aglaia3/…/aglaia3/api/v2/Role.java`
Controller interface	`aglaia3/…/aglaia3/controller/ILetoController.java`
Controller (direct, embedded)	`aglaia3/…/aglaia3/controller/DirectLetoController.java`
Controller (XML-RPC)	`aglaia3/…/aglaia3/controller/SXmlRpcLetoController.java`
Permission tests	`aglaia3/src/test/…/aglaia3/api/v2/SilePermissionTest.java`
ConnectorUtil (LETO bridge)	`leto/…/leto/utils/ConnectorUtil.java`
XML-RPC handlers	`leto/…/leto/connector/HighLevelRepositoryConnector.java`
XML-RPC client	`shared/sxmlrpc/…/sxmlrpc/client/HighLevelConnector.java`

Login and accounts

Log in

Starts a session and returns the secret for signing.

POST /v2/login

If the credentials match a user, AGLAIA creates a secret for this app and returns it with the user's URI. Each login opens a new session and AGLAIA keeps only a limited number per user, so log in once and reuse the secret; log out when done.

Request body application/json

email string required: Login name of the user.
password string required: Password of the user.
ontology string: Ontology of the session, if not the default.

{ "email": "you@example.com", "password": "your password" }

Response application/json

secret string: Secret for the Authentication header.
uri string: URI of the user.

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/login" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"your password"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/login", { "email": "you@example.com", "password": "your password" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/login", {"email": "you@example.com", "password": "your password"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/login", """
        { "email": "you@example.com", "password": "your password" }
        """, false);
System.out.println(result);

Response exampleapplication/json

{
  "secret": "6c0b9d6e1f2a4c8b…",
  "uri": "urn:uuid:0e3e6c9a-2b7f-4f19-9d41-5c8a1e7b3f20"
}

Log in with a licence

Starts a session for a licensed device.

POST /v2/login/license

If the device URI and the client serial number match, AGLAIA returns a secret, the user's URI and the licence data.

Request body application/json

{ "deviceUri": "urn:uuid:5b1f…", "serial": "ABCD-EFGH-1234" }

Response application/json

secret string: Secret for the Authentication header.
uri string: URI of the user.
validFrom string: Start of the licence.
validTo string: End of the licence.
allowedDevices integer: Number of devices the licence allows.
registeredDevices integer: Number of devices registered so far.

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/login/license" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"deviceUri":"urn:uuid:5b1f…","serial":"ABCD-EFGH-1234"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/login/license", { "deviceUri": "urn:uuid:5b1f…", "serial": "ABCD-EFGH-1234" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/login/license", {"deviceUri": "urn:uuid:5b1f…", "serial": "ABCD-EFGH-1234"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/login/license", """
        { "deviceUri": "urn:uuid:5b1f…", "serial": "ABCD-EFGH-1234" }
        """, false);
System.out.println(result);

Log out

Ends the session; the secret is invalid from now on.

GET /v2/logout Auth

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/logout'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}GET${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("GET", "/v2/logout");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("GET", "/v2/logout")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("GET", "/v2/logout", null);
System.out.println(result);

Response exampleapplication/json

{}

Register a user

Creates a deactivated user and e-mails the activation key.

POST /v2/register

Request body application/json

{ "email": "new.user@example.com", "password": "a good password", "firstname": "Ada", "lastname": "Lovelace" }

Response application/json

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/register" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"new.user@example.com","password":"a good password","firstname":"Ada","lastname":"Lovelace"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/register", {
  "email": "new.user@example.com",
  "password": "a good password",
  "firstname": "Ada",
  "lastname": "Lovelace"
}, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/register", {
    "email": "new.user@example.com",
    "password": "a good password",
    "firstname": "Ada",
    "lastname": "Lovelace",
}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/register", """
        {
          "email": "new.user@example.com",
          "password": "a good password",
          "firstname": "Ada",
          "lastname": "Lovelace"
        }
        """, false);
System.out.println(result);

Response exampleapplication/json

{ "email": "new.user@example.com" }

Register an active user

Creates a user that can log in at once (needs a user allowed to create users).

POST /v2/register/pronto Auth

Request body application/json

{ "email": "new.user@example.com", "password": "a good password", "firstname": "Ada", "lastname": "Lovelace" }

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/register/pronto'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"new.user@example.com","password":"a good password","firstname":"Ada","lastname":"Lovelace"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/register/pronto", {
  "email": "new.user@example.com",
  "password": "a good password",
  "firstname": "Ada",
  "lastname": "Lovelace"
});
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/register/pronto", {
    "email": "new.user@example.com",
    "password": "a good password",
    "firstname": "Ada",
    "lastname": "Lovelace",
})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/register/pronto", """
        {
          "email": "new.user@example.com",
          "password": "a good password",
          "firstname": "Ada",
          "lastname": "Lovelace"
        }
        """);
System.out.println(result);

Response exampleapplication/json

{ "email": "new.user@example.com" }

Get a redirect key

Creates a key that logs the user in to another app.

POST /v2/fetch-key/redirect Auth

The other app exchanges the key for its own secret with POST /v2/use-key/redirect.

Request body application/json

{ "appId": "notes" }

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/fetch-key/redirect'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"appId":"notes"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/fetch-key/redirect", { "appId": "notes" });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/fetch-key/redirect", {"appId": "notes"})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/fetch-key/redirect", """
        { "appId": "notes" }
        """);
System.out.println(result);

Response exampleapplication/json

{ "key": "c2a7…" }

Get a password key

Returns a password key if the password matches the current user.

POST /v2/fetch-key/password Auth

Request body application/json

{ "password": "your password" }

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/fetch-key/password'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"password":"your password"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/fetch-key/password", { "password": "your password" });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/fetch-key/password", {"password": "your password"})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/fetch-key/password", """
        { "password": "your password" }
        """);
System.out.println(result);

Response exampleapplication/json

{ "key": "9e14…" }

Forgot password

Creates a password key and sends it by e-mail.

POST /v2/mail-key/password

Request body application/json

{ "email": "you@example.com" }

Response application/json

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/mail-key/password" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/mail-key/password", { "email": "you@example.com" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/mail-key/password", {"email": "you@example.com"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/mail-key/password", """
        { "email": "you@example.com" }
        """, false);
System.out.println(result);

Response exampleapplication/json

{ "email": "you@example.com" }

Change e-mail address

Creates an e-mail key and sends it to the new address.

POST /v2/mail-key/email Auth

Request body application/json

{ "email": "new.address@example.com" }

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/mail-key/email'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"new.address@example.com"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/mail-key/email", { "email": "new.address@example.com" });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/mail-key/email", {"email": "new.address@example.com"})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/mail-key/email", """
        { "email": "new.address@example.com" }
        """);
System.out.println(result);

Response exampleapplication/json

{ "email": "new.address@example.com" }

Activate a user

Activates the user of a valid (not too old) activation key.

POST /v2/use-key/activation

Request body application/json

{ "key": "4f0d…" }

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/use-key/activation" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"key":"4f0d…"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/use-key/activation", { "key": "4f0d…" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/use-key/activation", {"key": "4f0d…"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/use-key/activation", """
        { "key": "4f0d…" }
        """, false);
System.out.println(result);

Use a redirect key

Exchanges a redirect key for a new secret.

POST /v2/use-key/redirect

Request body application/json

{ "key": "c2a7…" }

Response application/json

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/use-key/redirect" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"key":"c2a7…"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/use-key/redirect", { "key": "c2a7…" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/use-key/redirect", {"key": "c2a7…"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/use-key/redirect", """
        { "key": "c2a7…" }
        """, false);
System.out.println(result);

Response exampleapplication/json

{ "secret": "77ab…", "email": "you@example.com", "uri": "urn:uuid:0e3e6c9a-…" }

Set a new password

Sets the password of the user of a valid password key.

POST /v2/use-key/password

Request body application/json

{ "key": "9e14…", "password": "a new password" }

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/use-key/password" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"key":"9e14…","password":"a new password"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/use-key/password", { "key": "9e14…", "password": "a new password" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/use-key/password", {"key": "9e14…", "password": "a new password"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/use-key/password", """
        { "key": "9e14…", "password": "a new password" }
        """, false);
System.out.println(result);

Confirm the new e-mail address

Sets the e-mail address of the user of a valid e-mail key.

POST /v2/use-key/email

Request body application/json

{ "key": "1b8c…" }

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/use-key/email" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"key":"1b8c…"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/use-key/email", { "key": "1b8c…" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/use-key/email", {"key": "1b8c…"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/use-key/email", """
        { "key": "1b8c…" }
        """, false);
System.out.println(result);

Change password

Changes the password of the logged in user.

PATCH /v2/user/password Auth

Request body application/json

{ "password": "a new password" }

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/user/password'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}PATCH${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X PATCH "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"password":"a new password"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("PATCH", "/v2/user/password", { "password": "a new password" });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("PATCH", "/v2/user/password", {"password": "a new password"})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("PATCH", "/v2/user/password", """
        { "password": "a new password" }
        """);
System.out.println(result);

Ontologies

List ontologies

The URIs of all ontologies registered in AGLAIA.

GET /v2/ontology/list

Use one of these URIs in the Ontology header. New ontologies are registered in AGLAIA's configuration (beans.xml) by its administrator.

Response application/json

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s "$ALISE_API/v2/ontology/list" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication"
const result = await aglaia.request("GET", "/v2/ontology/list", undefined, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("GET", "/v2/ontology/list", signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("GET", "/v2/ontology/list", null, false);
System.out.println(result);

Response exampleapplication/json

[
  "http://library.alise.systems/ontology/leto/core#",
  "http://library.alise.systems/ontology/polis#",
  "http://library.alise.systems/ontology/polis/notes#",
  …
]

Download an ontology

The OWL file of an ontology, Base64 encoded.

POST /v2/ontology/owl

Request body application/json

{ "uri": "http://library.alise.systems/ontology/polis#" }

Response application/json

uri string: URI of the ontology.
owl string: The OWL (RDF/XML) file, Base64 encoded.

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s -X POST "$ALISE_API/v2/ontology/owl" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"uri":"http://library.alise.systems/ontology/polis#"}'

// aglaia: the client from "Authentication"
const result = await aglaia.request("POST", "/v2/ontology/owl", { "uri": "http://library.alise.systems/ontology/polis#" }, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("POST", "/v2/ontology/owl", {"uri": "http://library.alise.systems/ontology/polis#"}, signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("POST", "/v2/ontology/owl", """
        { "uri": "http://library.alise.systems/ontology/polis#" }
        """, false);
System.out.println(result);

Response exampleapplication/json

{
  "uri": "http://library.alise.systems/ontology/polis#",
  "owl": "PD94bWwgdmVyc2lvbj0iMS4wIj8+CjwhLS0KICBwb2xpcyBvbnRv…"
}

Ontology specification

Categories, attributes and Slink types of the ontology, as JSON.

GET /v2/ontology/spect

The specification ("Spect") of the ontology selected with the Ontology header: which categories exist and which attributes and Slinks a Sile of each category can have, the value type (range) of every attribute, and the target categories of every Slink type. Build forms and validate Siles from it.

Response application/json

categories[] array: id, and the attributes and slinks a Sile of this category can have.
attributes[] array: id and range: the XML Schema type of the values.
slinks[] array: id and range: the categories a Slink of this type may point to.
namespaces object: Prefixes used in the ontology.

# ALISE_API, ALISE_ONTOLOGY: see "Authentication"
curl -s "$ALISE_API/v2/ontology/spect" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication"
const result = await aglaia.request("GET", "/v2/ontology/spect", undefined, { signed: false });
console.log(result);

# aglaia: the client from "Authentication"
result = aglaia.request("GET", "/v2/ontology/spect", signed=False)
print(result)

// aglaia: the client from "Authentication"
String result = aglaia.send("GET", "/v2/ontology/spect", null, false);
System.out.println(result);

Response exampleapplication/json

{
  "categories": [
    {
      "id": "Application",
      "attributes": ["frontendEntry", "status", "icon", "vendor", "version", "description", …],
      "slinks": ["consistsOf", "dependsOn"]
    },
    …
  ],
  "attributes": [
    { "id": "vendor", "range": "http://www.w3.org/2001/XMLSchema#string" },
    …
  ],
  "slinks": [
    { "id": "consistsOf", "range": ["Microservice"] },
    { "id": "memberOf", "range": ["Group"] },
    …
  ],
  "namespaces": {}
}

Subcategories

The subcategories of a category.

GET /v2/category/children/{category} Auth

Returns the short names of the direct subcategories; [] if there are none. Category names are resolved in the server's default ontology, see Notes.

Parameters

category string path required: Short name of the category, as in the specification.

Response application/json

Errors

500: Unknown category (Cannot invoke … because "cat" is null).

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/category/children/Application'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}GET${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("GET", "/v2/category/children/Application");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("GET", "/v2/category/children/Application")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("GET", "/v2/category/children/Application", null);
System.out.println(result);

Response exampleapplication/json

[]

Siles

Get a Sile

One Sile by its URI.

GET /v2/sile/{id} Auth

Parameters

id string path required: URI of the Sile.
content string query default metadata: How much to return: label, metadata, binary or all, see Siles.

Response application/json

Errors

404: Sile not found.

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}GET${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f", null);
System.out.println(result);

Response exampleapplication/json

{
  "uri": "urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f",
  "label": "Notes",
  "categories": ["Application"],
  "attributes": {
    "vendor": ["AL!SE.SYSTEMS"],
    "frontendType": ["wicket-panel"],
    …
  },
  "slinks": {}
}

Create a Sile

Creates a Sile; AGLAIA assigns the URI.

POST /v2/sile Auth

Request body application/json

{
  "label": "Customer portal",
  "categories": ["Application"],
  "attributes": { "vendor": ["AL!SE.SYSTEMS"], "version": ["1.0.0"] },
  "slinks": {}
}

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"label":"Customer portal","categories":["Application"],"attributes":{"vendor":["AL!SE.SYSTEMS"],"version":["1.0.0"]},"slinks":{}}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/sile", {
  "label": "Customer portal",
  "categories": ["Application"],
  "attributes": { "vendor": ["AL!SE.SYSTEMS"], "version": ["1.0.0"] },
  "slinks": {}
});
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/sile", {
    "label": "Customer portal",
    "categories": ["Application"],
    "attributes": {"vendor": ["AL!SE.SYSTEMS"], "version": ["1.0.0"]},
    "slinks": {},
})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/sile", """
        {
          "label": "Customer portal",
          "categories": ["Application"],
          "attributes": { "vendor": ["AL!SE.SYSTEMS"], "version": ["1.0.0"] },
          "slinks": {}
        }
        """);
System.out.println(result);

Response exampleapplication/json

{
  "uri": "urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf",
  "label": "Customer portal",
  "categories": ["Application"],
  "attributes": { "vendor": ["AL!SE.SYSTEMS"], "version": ["1.0.0"] },
  "slinks": {}
}

Change a Sile

Changes only the given fields.

PATCH /v2/sile/{id} Auth

Parameters

id string path required: URI of the Sile.

Request body application/json

{ "label": "Customer portal (new)" }

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}PATCH${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X PATCH "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"label":"Customer portal (new)"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("PATCH", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf", { "label": "Customer portal (new)" });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("PATCH", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf", {"label": "Customer portal (new)"})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("PATCH", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf", """
        { "label": "Customer portal (new)" }
        """);
System.out.println(result);

Response exampleapplication/json

{
  "uri": "urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf",
  "label": "Customer portal (new)",
  …
}

Replace a Sile

Replaces the Sile with the one sent.

PUT /v2/sile/{id} Auth

Parameters

id string path required: URI of the Sile.

Request body application/json

{
  "label": "Customer portal",
  "categories": ["Application"],
  "attributes": { "version": ["1.1.0"] },
  "slinks": {}
}

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}PUT${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X PUT "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"label":"Customer portal","categories":["Application"],"attributes":{"version":["1.1.0"]},"slinks":{}}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("PUT", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf", {
  "label": "Customer portal",
  "categories": ["Application"],
  "attributes": { "version": ["1.1.0"] },
  "slinks": {}
});
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("PUT", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf", {
    "label": "Customer portal",
    "categories": ["Application"],
    "attributes": {"version": ["1.1.0"]},
    "slinks": {},
})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("PUT", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf", """
        {
          "label": "Customer portal",
          "categories": ["Application"],
          "attributes": { "version": ["1.1.0"] },
          "slinks": {}
        }
        """);
System.out.println(result);

Response exampleapplication/json

{
  "uri": "urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf",
  "label": "Customer portal",
  "attributes": { "version": ["1.1.0"] },
  …
}

Delete a Sile

Marks the Sile as deleted.

DELETE /v2/sile/{id} Auth

The Sile disappears from all reads. It is removed for good by DELETE /v2/sile/squeeze.

Parameters

id string path required: URI of the Sile.

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}DELETE${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X DELETE "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("DELETE", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("DELETE", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("DELETE", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf", null);
System.out.println(result);

Response exampleapplication/json

{}

Finding Siles

Filter Siles

All Siles that match a filter.

POST /v2/sile/filter Auth

The body is a filter, see Filters.

Parameters

content string query default metadata: How much to return per Sile: uri, date, label, metadata, binary or all.
limit integer query default all: Return at most this many Siles.
offset integer query default 0: Skip this many Siles first.

Request body application/json

[ { "type": "category", "label": "Application" } ]

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/filter?content=label&limit=10'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '[{"type":"category","label":"Application"}]'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/sile/filter?content=label&limit=10", [{ "type": "category", "label": "Application" }]);
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/sile/filter?content=label&limit=10", [{"type": "category", "label": "Application"}])
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/sile/filter?content=label&limit=10", """
        [{ "type": "category", "label": "Application" }]
        """);
System.out.println(result);

Response exampleapplication/json

[
  { "uri": "urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f", "label": "Notes" },
  { "uri": "urn:uuid:5e9a1c3d-7f4b-4a0c-9e8d-3c4d5e6f7a8b", "label": "Resource Monitor" },
  …
]

Filter Siles, URIs only

The URIs of all Siles that match a filter.

POST /v2/sile/filter/uris Auth

The body is a filter, see Filters. Category names are resolved in the default ontology, see Notes.

Request body application/json

[ { "type": "labelvalue", "value": "Notes" } ]

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/filter/uris'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '[{"type":"labelvalue","value":"Notes"}]'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/sile/filter/uris", [{ "type": "labelvalue", "value": "Notes" }]);
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/sile/filter/uris", [{"type": "labelvalue", "value": "Notes"}])
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/sile/filter/uris", """
        [{ "type": "labelvalue", "value": "Notes" }]
        """);
System.out.println(result);

Response exampleapplication/json

["urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f"]

Count Siles

How many Siles match a filter.

POST /v2/sile/filter/count Auth

The body is a filter, see Filters. Category names are resolved in the default ontology, see Notes.

Request body application/json

[ { "type": "labelvalue", "value": "Notes" } ]

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/filter/count'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '[{"type":"labelvalue","value":"Notes"}]'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/sile/filter/count", [{ "type": "labelvalue", "value": "Notes" }]);
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/sile/filter/count", [{"type": "labelvalue", "value": "Notes"}])
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/sile/filter/count", """
        [{ "type": "labelvalue", "value": "Notes" }]
        """);
System.out.println(result);

Response exampleapplication/json

{ "count": 1 }

Sile permissions

Get permissions

The read and write permissions of every role on a Sile.

GET /v2/sile/{id}/permissions Auth

Each key is a role name, each value read, write or read,write.

Parameters

id string path required: URI of the Sile.

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}GET${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions", null);
System.out.println(result);

Response exampleapplication/json

{ "Editor": "read,write", "Viewer": "read", "Colleague": "read" }

Set permissions

Grants or removes read and write permission of one role.

PUT /v2/sile/{id}/permissions Auth

Creates or removes the tags <role>:read and <role>:write on the Sile. The calling user needs write permission on the Sile. Send one request per role.

Parameters

id string path required: URI of the Sile.

Request body application/json

roleName string required: Name of the role, e.g. Editor.
canRead boolean: Whether the role may read the Sile.
canWrite boolean: Whether the role may change and delete the Sile.

{ "roleName": "Colleague", "canRead": true, "canWrite": false }

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf/permissions'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}PUT${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X PUT "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"roleName":"Colleague","canRead":true,"canWrite":false}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("PUT", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf/permissions", { "roleName": "Colleague", "canRead": true, "canWrite": false });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("PUT", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf/permissions", {"roleName": "Colleague", "canRead": True, "canWrite": False})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("PUT", "/v2/sile/urn:uuid:8ac023bf-27e1-36eb-9985-df9bc261f1bf/permissions", """
        { "roleName": "Colleague", "canRead": true, "canWrite": false }
        """);
System.out.println(result);

Response exampleapplication/json

{ "success": true }

Check a permission

Whether a user has a permission on a Sile.

GET /v2/sile/{id}/permissions/check Auth

Parameters

id string path required: URI of the Sile.
user string query required: Login name of the user.
type string query required: read, write or delete.

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions/check?user=john@example.com&type=read'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}GET${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions/check?user=john@example.com&type=read");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions/check?user=john@example.com&type=read")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("GET", "/v2/sile/urn:uuid:3c7e9a1b-5d2f-4e8a-9c6b-1a2b3c4d5e6f/permissions/check?user=john@example.com&type=read", null);
System.out.println(result);

Response exampleapplication/json

{ "permitted": true }

Roles

Get a role

A role group by its id.

GET /v2/role/{id} Auth

Parameters

id string path required: Id of the role.

Errors

404: Role not found.

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/role/Editor'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}GET${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("GET", "/v2/role/Editor");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("GET", "/v2/role/Editor")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("GET", "/v2/role/Editor", null);
System.out.println(result);

Create a role

Creates a role group.

POST /v2/role Auth

Request body application/json

roleId string required: Id of the new role.
readSlinks array: Slink types the role may read.
writeSlinks array: Slink types the role may write.
superRoleId string: Role this role inherits from.

{ "roleId": "Editor", "readSlinks": ["memberOf"], "writeSlinks": ["memberOf"], "superRoleId": "Viewer" }

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/role'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}POST${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X POST "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"roleId":"Editor","readSlinks":["memberOf"],"writeSlinks":["memberOf"],"superRoleId":"Viewer"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("POST", "/v2/role", {
  "roleId": "Editor",
  "readSlinks": ["memberOf"],
  "writeSlinks": ["memberOf"],
  "superRoleId": "Viewer"
});
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("POST", "/v2/role", {
    "roleId": "Editor",
    "readSlinks": ["memberOf"],
    "writeSlinks": ["memberOf"],
    "superRoleId": "Viewer",
})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("POST", "/v2/role", """
        {
          "roleId": "Editor",
          "readSlinks": ["memberOf"],
          "writeSlinks": ["memberOf"],
          "superRoleId": "Viewer"
        }
        """);
System.out.println(result);

Change a role

Changes the given fields of a role.

PATCH /v2/role/{id} Auth

Parameters

id string path required: Id of the role.

Request body application/json

{ "superRoleId": "Viewer" }

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/role/Editor'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}PATCH${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X PATCH "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"superRoleId":"Viewer"}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("PATCH", "/v2/role/Editor", { "superRoleId": "Viewer" });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("PATCH", "/v2/role/Editor", {"superRoleId": "Viewer"})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("PATCH", "/v2/role/Editor", """
        { "superRoleId": "Viewer" }
        """);
System.out.println(result);

Add Slinks to a role

Adds Slink types the role may read or write.

PATCH /v2/role/add/{id} Auth

Parameters

id string path required: Id of the role.

Request body application/json

{ "readSlinks": ["dependsOn"], "writeSlinks": [] }

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/role/add/Editor'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}PATCH${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X PATCH "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"readSlinks":["dependsOn"],"writeSlinks":[]}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("PATCH", "/v2/role/add/Editor", { "readSlinks": ["dependsOn"], "writeSlinks": [] });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("PATCH", "/v2/role/add/Editor", {"readSlinks": ["dependsOn"], "writeSlinks": []})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("PATCH", "/v2/role/add/Editor", """
        { "readSlinks": ["dependsOn"], "writeSlinks": [] }
        """);
System.out.println(result);

Remove Slinks from a role

Removes Slink types the role may read or write.

PATCH /v2/role/remove/{id} Auth

Parameters

id string path required: Id of the role.

Request body application/json

{ "readSlinks": ["dependsOn"], "writeSlinks": [] }

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/role/remove/Editor'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}PATCH${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X PATCH "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY" \
  -H 'Content-Type: application/json' \
  -d '{"readSlinks":["dependsOn"],"writeSlinks":[]}'

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("PATCH", "/v2/role/remove/Editor", { "readSlinks": ["dependsOn"], "writeSlinks": [] });
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("PATCH", "/v2/role/remove/Editor", {"readSlinks": ["dependsOn"], "writeSlinks": []})
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("PATCH", "/v2/role/remove/Editor", """
        { "readSlinks": ["dependsOn"], "writeSlinks": [] }
        """);
System.out.println(result);

Maintenance

Purge deleted Siles

Removes all deleted Siles for good (administrators only).

DELETE /v2/sile/squeeze Auth

Response application/json

# ALISE_API, ALISE_USER, ALISE_SECRET, ALISE_NONCE, ALISE_ONTOLOGY: see "Authentication"
P='/v2/sile/squeeze'
ALISE_NONCE=$((ALISE_NONCE + 1))
DIGEST=$(printf '%s' "${ALISE_SECRET}DELETE${P}${ALISE_NONCE}" | sha256sum | cut -d' ' -f1)
curl -s -X DELETE "$ALISE_API$P" \
  -H "Authentication: hmac $ALISE_USER:$ALISE_NONCE:$DIGEST" \
  -H "Ontology: $ALISE_ONTOLOGY"

// aglaia: the client from "Authentication", logged in
const result = await aglaia.request("DELETE", "/v2/sile/squeeze");
console.log(result);

# aglaia: the client from "Authentication", logged in
result = aglaia.request("DELETE", "/v2/sile/squeeze")
print(result)

// aglaia: the client from "Authentication", logged in
String result = aglaia.request("DELETE", "/v2/sile/squeeze", null);
System.out.println(result);

Response exampleapplication/json

{ "purged": 3 }