Ontopic Docs

# Using the Web API

Starting from Ontopic Suite 2025.1.0

The Web API enables you to perform most actions available through the User Interface programmatically. You can perform various operations, including:

  • Create and manage projects
  • Edit the mapping, ontology, lenses and snapshot them
  • Manage access policies for projects and deployments
  • Deploy Semantic SQL and SPARQL endpoints
  • Query the KG using SPARQL
  • Reformulate SPARQL and Semantic SQL queries into SQL queries ready to be executed by the data source
  • Materialize KGs into RDF files
  • Access the Certificate Authority for validating connections to the Semantic SQL endpoint using the PostgreSQL protocol

Most of the operations are organized around projects.

The Web API is documented using an OpenAPI 3.0 specification (available on your Ontopic Suite instance at /api-docs.json (opens new window)) and can be tested through the Swagger UI (at /api-ui (opens new window)). To explore the Web API, visit the Swagger page of this documentation.

# Authorization

You can use the Web API with session cookies (in the web browser) or basic authentication for accounts using that scheme. However, using OAuth 2 bearer access tokens is strongly recommended in production environments.

Ontopic Suite supports the User-to-Machine process where the client application impersonates the user, performing actions on behalf of the user. The list of actions that can be delegated to the client application is controlled through OAuth scopes (see the list here).

How to obtain access tokens depends on the standard procedures of your identity provider. In the remainder of this section, we illustrate a common configuration.

# Non-Web OAuth client with Microsoft Entra

If your OAuth client application cannot interact with the user through a web UI, we recommend using the Device Authorization Flow (opens new window). Here we describe how to configure it with Microsoft Entra.

To configure the client in Microsoft Entra (opens new window):

  1. Register a client application in App registrations
  2. In App Registration > Manage > Authentication > Settings, enable Allow public client flows
  3. In App Registration > Manage > Configured permissions, add all the delegated permissions from the Ontopic Suite application
  4. Grant admin consent for these permissions

Afterwards, you just have to follow the flow described in the Microsoft Entra documentation (opens new window). In a nutshell, the client application should:

  1. initiate the device code flow through an HTTP POST request
  2. ask the user to connect to https://microsoft.com/devicelogin (opens new window), enter the user code returned by the previous request and login
  3. ask the user to confirm he/she has logged in (e.g. by pressing enter in a terminal)
  4. request the access token through another HTTP POST request.

← Semantic SQL →