ORKG Backend API

This repository contains a backend API for the Open Research Knowledge Graph (ORKG) written in Kotlin. It is based on the Spring Framework and uses Gradle for its build process.

REST API documentation

The documentation can be found at https://tibhannover.gitlab.io/orkg/orkg-backend/api-doc/index.html. Alternatively, an OpenAPI specification can be fetched directly from the API at https://orkg.org/api.

Client API libraries

The backend API project provides two auto-generated client libraries, based on OpenAPI. The version of the client library matches the version of the backend API.

TypeScript client

Prerequisites

Please follow the respective installation instructions for TypeScript 4.0 or later. Add the package registry of this project to your .npmrc by running:

Note	This only needs to be done once.

echo @orkg:registry=https://gitlab.com/api/v4/projects/12710144/packages/npm/ >> .npmrc

Installation

To install the TypeScript client, run:

npm install @orkg/orkg-client

Usage

Configuration

import {Configuration, ResourcesApi, ThingsApi} from '@orkg/orkg-client';

const configuration = new Configuration({basePath: "https://incubating.orkg.org"});
const thingsApi = new ThingsApi(configuration)
const resourcesApi = new ResourcesApi(configuration)

Fetching a thing by id

Async API usage:

thingsApi.findById({id: "R1000"})
    .then((result) => console.log(result))
    .catch(async (error) => console.log(await error.response.json()));

Sync API usage:

try {
    const thing = await thingsApi.findById({id: "R1000"});
    console.log(thing);
} catch (error: any) {
    console.log(await error.response.json());
}

Creating a new resource

Async API usage:

resourcesApi.createRaw({createResourceRequest: {label: "example"}})
    .then((result) => console.log(result.raw.headers.get("Location")))
    .catch(async (error) => console.log(await error.response.json()));

Sync API usage:

try {
    const resource = await resourcesApi.createRaw({createResourceRequest: {label: "example"}});
    const location = resource.raw.headers.get("Location");
    console.log(location);
} catch (error: any) {
    console.log(await error.response.json());
}

Python client

Prerequisites

Please follow the respective installation instructions for Python 3.9 or later.

Installation

To install the Python client, run:

pip install orkg_client --index-url https://gitlab.com/api/v4/projects/12710144/packages/pypi/simple

Usage

Configuration

from orkg_client import ApiClient, Configuration, ThingsApi, ResourcesApi, CreateResourceRequest
from orkg_client.exceptions import ApiException

configuration = Configuration(host="https://incubating.orkg.org")
api_client = ApiClient(configuration=configuration)
things_api = ThingsApi(api_client)
resources_api = ResourcesApi(api_client)

Fetching a thing by id

try:
    thing = things_api.find_by_id(id="R1000")
    print(thing.actual_instance)
except ApiException as error:
    print(error.data)

Creating a new resource

try:
    resource = resources_api.create_with_http_info(CreateResourceRequest(label="example"))
    location = resource.headers["Location"]
    print(location)
except ApiException as error:
    print(error.data)

Building and running

Prerequisites

The backend API can be run stand-alone. However, it needs other services to start properly. Services are managed via Docker. Please follow the respective installation instructions for your operating system or distribution.

Cloning

The backend API project uses git submodules in order to include external components in the build process. You can clone the repository including all of its submodules by running:

git clone --recurse-submodules https://gitlab.com/TIBHannover/orkg/orkg-backend.git

Or if you already cloned the project without including submodules:

cd orkg-backend
git submodule init --recursive
git submodule update

Stand-alone application

Note	Running the application stand-alone is mostly for development purposes. It still needs Neo4j and PostgreSQL configured and running. If you want to test the application, please refer to the section Building a Docker image below.

To build and run the API, type:

./gradlew bootRun

This will start a server running on http://localhost:8080.

The REST entry-point is http://localhost:8080/api/.

Building a Docker image

Note	The following commands assume that you added your user to the docker group as suggested in the documentation. If you did not do so, you have to prefix all commands with sudo.

The Docker image can be built with Jib. Run:

./gradlew jibDockerBuild

The application can be run via Docker Compose. After installing it, run:

docker compose up -d

This will start the application image and all dependent containers. It will take care of linking all containers so the services can see each other. You can start and connect all services yourself but this is not recommended.

The application can be accessed via http://localhost:8080/. The other services can be accessed via the URLs described in table "Images and their default end-points".

To diagnose problems, check the logs with:

docker compose logs -f

To restart from scratch, run:

docker compose down

Data is saved to named volumes for Neo4j and Postgres, respectively, and persists even if you destroy the containers. If you also need to get rid of the data use the docker volume sub-commands to locate and remove them.

Docker images

Note	This section is only relevant if you want to work with some of the components in isolation. Please refer to the section Building a Docker image if you want to run the application via Docker.

Caution

The recommended way to start the Backend is (still) via Docker Compose.

Image end-points

The images will provide the following end-points:

Table 1. Images and their default end-points

Image	Container name	End-points
registry.gitlab.com/tibhannover/orkg/orkg-backend	orkg-backend-api-1	http://localhost:8080/api/ (REST API)
neo4j	orkg-backend-neo4j-1	http://localhost:7474/browser/ (HTTP) localhost:7687 (BOLT)
postgres	orkg-backend-postgres-1	localhost:5432

All exposed ports are bound to localhost (IPv4 and IPv6) to not "leak" to all networks. If you need to expose those to your host network, refer to the Docker documentation and change the Compose file accordingly.

Notes on the Neo4j Docker image

The Neo4j Docker image includes the following extensions:

• APOC Core

• APOC Extended

APOC Core and APOC Extended are required by the ORKG. You need to include them when you set up Neo4j in your environment manually.

Gradle Subprojects (a. k. a. Modules)

You can create an overview of the Gradle subproject dependencies as Mermaid diagram, which can be converted to SVG or PDF, like this:

./gradlew createModuleGraph
mmdc -i modules.mermaid -e svg -o modules.svg -c mermaid-config.json

The configuration file increases the maximum number of nodes allowed for processing. If you run into issues, this number can be increased further.