dasch-swiss / Dsp Api
Programming Languages
Labels
Projects that are alternatives of or similar to Dsp Api
Knora — Knowledge Organization, Representation, and Annotation
Knora is a server application for storing, sharing, and working with primary sources and data in the humanities.
It is developed by the 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 .
Knora is free software, released under the GNU Affero General Public License.
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
- Knora API v2
- Knora Admin API
- Distribution packaging using Docker
New features under development
- See the Roadmap
Requirements
For developing and testing the API server
Each developer machine should have the following prerequisites installed:
- Linux or macOS (with some caveats)
- Docker Desktop: https://www.docker.com/products/docker-desktop
- Homebrew (on macOS): https://brew.sh
- OpenJDK 11
- Bazel
Java Adoptopenjdk 11
To install, follow these steps:
brew tap AdoptOpenJDK/openjdk
brew cask install AdoptOpenJDK/openjdk/adoptopenjdk11
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`
Bazel build tools
To install, follow these steps:
npm install -g @bazel/bazelisk
This will install bazelisk which is
a wrapper to the bazel
binary. It will, when bazel
is run on the command line,
automatically install the supported Bazel version, defined in the .bazelversion
file in the root of the knora-api
repository.
For building the documentation
See docs/Readme.md.
Try it out
Run the Knora API server
With Bazel and Docker installed, 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.
To shut down the Knora-Stack:
make stack-down
Run the automated tests
Run :
make test
Running with Custom Folders
The $ make stack-up
target can be additionally configured thorough the
following environment variables:
-
KNORA_DB_HOME
: sets the path to the folder where the triplestore will store the database files -
KNORA_DB_IMPORT
: sets the path to the import directory accessible from inside the docker image
If the import and/or data directory are not set, then Docker volumes will be
used instead. Be aware on macOS, that setting the KNORA_DB_HOME
has a
significant negative impact on performance, because of how synchronization with
the VM, in which docker is running, is implemented.
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 IntelliJ IDEA 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, typegraphdb:test
orgraphdb-free:test
(depending on which triplestore you're using) at the SBT console in thewebapi
project. To run a single test, usegraphdb:test-only *NameOfTestSpec
. - Integration tests, which can involve Sipi, are under
src/it
. To run these, first start Sipi, then typeit:test
at the SBT console in thewebapi
project. - Browser interaction tests are under
salsah/src/test
, and are written using Selenium. To run these, you will need to unpack the correct ChromeDriver for your platform found undersalsah/lib/chromedriver
and put it in the same folder. Then start Sipi and the Knora API server, and typetest
at the SBT console in thesalsah
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.
Contact information
Technical
Please use the discuss.dasch.swiss forum for technical questions.
Administrative
Lukas Rosenthaler <[email protected]>
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 Youtrack. Since we started to use the release-please-action it's very important to set the PR title in the correct way, especially becuase all commits added within the pull request are squashed. Please read the official DSP Contribution Documentation carefully!
Acknowledgments
The Knora project is using YourKit for profiling.
YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.