search

kit-data-manager / pit-service

Typed PID Maker – Create, resolve and modify PIDs with typed constraints, e.g. for FAIR DOs.
https://kit-data-manager.github.io/webpage/typed-pid-maker/index.html
Apache License 2.0
3 stars 4 forks source link
fair fair-data fair-principles java spring-boot

readme

Typed PID Maker

License Java CI with Gradle

The Typed PID Maker enables the creation, maintenance, and validation of PIDs. It ensures the PID contains typed, machine-actionable information using validation. This is especially helpful in the context of FAIR Digital Objects (FAIR DOs / FDOs). To make this work, our validation strategy requires a reference to a registered Kernel Information Profile within the PID record, as defined by the recommendations of the Research Data Alliance (RDA). In the RDA context, this kind of service is called a "PIT service". We use Handle PIDs, which can be created using a Handle Prefix (not included). For testing or other local purposes, we support sandboxed PIDs, which require no external service.

Go to: Documentation | Configuration details | Features | Build | Run | License

Features

Some of the features are described in more detail in the following sections.

Search example

The search can be executed via the provided swagger interface (default location: http://localhost:8090/swagger-ui.html). For example, with the following request body you will get all record information:

{
  "query": {
    "regexp": {
      "pid": {
        "value": ".*",
        "flags": "ALL",
        "case_insensitive": true
      }
    }
  }
}

You can also use other http clients, like CURL. A CURL (which may be provided by swagger) request may look like this:

curl -X 'POST' \
  'http://localhost:8090/api/v1/search?page=0&size=20' \
  -H 'accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": {
    "regexp": {
      "pid": {
        "value": ".*",
        "flags": "ALL",
        "case_insensitive": true
      }
    }
  }
}'

The look of a PID (customization)

The detailed configuration documentation has a list of available properties which influence the way PIDs look. There is no functional benefit in PID customization. Some examples for possible PIDs with the Typed PID Maker:

If you have an interest in more customization, feel free to contact us.

In general, a PID is built like the following scheme:

PID = prefix + suffix
  1. The prefix is a string which is prepended to all your PIDs. It can be considered a namespace and is given to you by your PID system (here: the handle system). It usually ends with a slash (/) as a separator.
  2. The suffix is a random string, generated by the Typed PID Maker. This generation can be customized.

As the suffix is flexible, we can prepend a branding prefix to it, to show some relation to a project or institution. Please note that the branding is then part of the suffix, and therefore part of the whole PID. It can not be changed if the PID has already been registered. Of course, it can be changed for new PIDs. If a branding is applied, the scheme of a PID can be represented like the following:

PID = prefix + (branding + uniquely-generated-string)
               ^------------- <suffix> -------------^

All other configuration properties affect only the uniquely-generated-string. For example, you may choose a different generation method (UUID (default) or Hex Chunks) enforce casing (lower-case, upper-case).

How to build

Note: Alternatively, you can use the docker image.

Required: Java SE Development Kit 21 (or openjdk 21) or higher

On Windows, replace ./gradlew with gradlew.bat.

After a successful build, a jar file containing the entire service is created at build/libs/TypedPIDMaker-$(version).jar.

How to run

Currently, you can either run it via docker or via the compiled JAR file.

Running via docker

Required: Up-to-date Docker (or Docker Desktop) installation

We provide docker images hosted on GitHub.

Running the compiled JAR file

For development purposes, the easiest way to run the service with your configuration file is:

./gradlew run --args="--spring.config.location=config/application-default.properties"

This command will use the default settings, set and documented in the file config/application.properties (see command line options). Changes in this file will require a restart of the Typed PID Maker, in case it is already running. If you change the location of the file or want to use another configuration, you may adjust the path in the command above or use one of the default locations for spring boot configurations.

For production use, the service can also be started directly like this:

./build/libs/TypedPIDMaker-$(version).jar

The start will take a moment, and indicate its readiness with Spring is started! on stdout. As soon as the microservice is started, you can browse to

OpenAPI / Swagger documentation:
http://localhost:8090/swagger-ui.html

in order to see available RESTful endpoints and their documentation. You may have to adapt the port according to your local settings. Furthermore, you can use this web interface to test single API calls in order to get familiar with the service.

Details on the version number and other build information can be found on http://localhost:8090/actuator/info.

Command line options

License

The license for the KIT Data Manager source code is available within the LICENSE file.