Skip to content

Latest commit

 

History

History
173 lines (116 loc) · 7.3 KB

README.md

File metadata and controls

173 lines (116 loc) · 7.3 KB
Raw

DSP-API — DaSCH Service Platform API

Github Docker CI

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.

Status

Stable

Beta stage

Requirements

For developing and testing the API server

Each developer machine should have the following prerequisites installed:

Java Adoptopenjdk 11

To install, follow these steps:

brew tap AdoptOpenJDK/openjdk
brew install AdoptOpenJDK/openjdk/adoptopenjdk11 --cask

To pin the version of Java, please add this environment variable to you startup script (bashrc, etc.):

export JAVA_HOME=`/usr/libexec/java_home -v 11`

For building the documentation

See docs/Readme.md.

Try it out

Run the Knora API server

Run the following to create a test repository and load some test data into the triplestore:

make init-db-test

Then we need to start knora-api after loading the data:

make stack-up

Then try opening http://localhost:3333/v2/resources/http%3A%2F%2Frdfh.ch%2F0803%2Fc5058f3a in a web browser. You should see a response in JSON-LD describing a book.

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

To shut down the Knora-Stack:

make stack-down

Run the automated tests

Run :

make test

How to Contribute

You can help by testing Knora with your data, making bug reports, improving the documentation, and adding features that you need.

First, open an issue to describe your problem or idea. We may ask you to submit a pull request implementing the desired functionality.

Coding conventions

Use camelCase for names of classes, variables, and functions. Make names descriptive, and don't worry if they're long.

Use Scalafmt in Visual Studio Code to format Scala code.

Use whitespace to make your code easier to read. Add lots of implementation comments describing what your code is doing, how it works, and why it works that way.

Tests

We write automated tests using ScalaTest. You can run them from the SBT console.

There are three sets of automated tests:

  • Unit tests, route-to-route tests, and end-to-end tests are under webapi/src/test. To run these, type test at the SBT console in the webapi project. To run a single test, use testOnly *NameOfTestSpec.
  • Integration tests, which can involve Sipi, are under src/it. To run these, first start Sipi, then type it:test at the SBT console in the webapi project.

Whenever you add a new feature or fix a bug, you should add one or more tests for the change you made.

Documentation

A pull request should include tests and documentation for the changes that were made. See the documentation README for information on writing Knora documentation.

Commit Message Schema

When writing commit messages, we follow the Conventional Commit messages rules. Get more information in our official DSP Contribution Documentation

Release Versioning Convention

The Knora project is following the Semantic Versioning convention for numbering the releases as defined by [http://semver.org]:

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 ontologies which are not backwards compatible.

Release Notes Generation

A pull request usually resolves one issue or user story defined on Jira. Since we started to use the release-please-action it's very important to set the PR title in the correct way, especially because all commits added within the pull request are squashed. Please read the official DSP Contribution Documentation carefully!