/dsp-api

DaSCH Service Platform API

Primary LanguageScalaApache License 2.0Apache-2.0

DSP-API — DaSCH Service Platform API

Github Docker CI Codacy Badge Codacy Badge

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:

JDK Temurin 21

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

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.

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:

just stack-init-test

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

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

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

docker-compose disable-v2

Shut down DSP-API:

just stack-stop

Run the automated tests

Automated tests are split into different source sets into slow running integration tests (i.e. tests which do IO or are using Testcontainers) and fast running unit tests.

Run unit tests:

sbt test

Run integration tests:

make integration-test

Run all tests:

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.