DSP-API — DaSCH Service Platform API

DSP is a server application for storing, sharing, and working with primary sources and data in the humanities.

It is developed by the Swiss National Data and Service Center for the Humanities at the University of Basel, and is supported by the Swiss Academy of Humanities and Social Sciences and the Swiss National Science Foundation.

DSP-API is free software, released under the Apache License, Version 2.0.

Features

• Stores humanities data as industry-standard RDF graphs, plus files for binary data such as digitized primary sources.
  • Designed to work with any standards-compliant RDF triplestore. Tested with Jena Fuseki.
• Based on OWL ontologies that express abstract, cross-disciplinary commonalities in the structure and semantics of research data.
• Offers a generic HTTP-based API, implemented in Scala, for querying, annotating, and linking together heterogeneous data in a unified way.
  • Handles authentication and authorization.
  • Provides automatic versioning of data.
• Uses Sipi, a high-performance media server implemented in C++.
• Designed to be be used with DSP-APP, a general-purpose, browser-based virtual research environment, as well as with custom user interfaces.

Requirements

For developing and testing DSP-API

Each developer machine should have the following prerequisites installed:

• Linux or macOS
• Docker Desktop
• Homebrew (macOS)
• JDK Temurin 21
• sbt
• just

JDK Temurin 21

Follow the steps described on https://sdkman.io/ to install SDKMAN. Then, follow these steps:

shell sdk ls java # choose the latest version of Temurin 21 sdk install java 21.x.y-tem

SDKMAN will take care of the environment variable JAVA_HOME.

EditorConfig

This repository contains a root-level .editorconfig to keep Markdown and YAML formatting consistent (e.g., 4-space list indents in Markdown, 2-space YAML). Most editors support EditorConfig natively or via a plugin; consider enabling it and format-on-save for consistent diffs.

For building the documentation

See docs/Readme.md.

Try it out

Run DSP-API

Create a test repository, load some test data into the triplestore, and start DSP-API:

shell just stack-init-test

Open http://localhost:4200/ in a web browser.

On first installation, errors similar to the following can come up:

text error decoding 'Volumes[0]': invalid spec: :/fuseki:delegated: empty section between colons

To solve this, you need to deactivate Docker Compose V2. This can be done in Docker Desktop either by unchecking the "Use Docker Compose V2" flag under "Preferences > General" or by running

text docker-compose disable-v2

Shut down DSP-API:

shell just stack-stop

Run the automated tests

Automated tests are split into different modules: fast unit tests, integration tests (service/repo/Sipi tests using Testcontainers), and end-to-end HTTP API tests.

Run unit tests:

shell sbt test

Run integration tests:

shell make test-it

Run end-to-end tests:

shell make test-e2e

Run all tests:

shell make test-all

Release Versioning Convention

The DSP-API release versioning follows the Semantic Versioning convention:

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

Additionally, we will also increment the MAJOR version in the case when any kind of changes to existing data would be necessary, e.g., any changes to the knora-base ontology which are not backwards compatible.