API

The API documentation is provided out-of-the-box by swagger-ui and springdoc-openapi.

One can configure this in the application.yaml file of the RDepot backend application (rdepot-app). By default it is configured as follows:

springdoc:
  pathsToMatch: /api/v2/**
  api-docs:
    path: /v2/api-docs
  swagger-ui:
    path: /docs/api.html
    disable-swagger-default-url: true
    url: /v2/api-docs
    display-query-params: true
  default-produces-media-type: application/json

The Swagger UI web application can be found on any running RDepot instance, at the following URL: http(s)://<rdepot-backend-public-url>/docs/api.html (see the springdoc.swagger-ui.path configuration parameter above).

The OpenAPI v3 specification in JSON can be found at the following URL: http(s)://<rdepot-backend-public-url>/v2/api-docs (see the springdoc.api-docs.path configuration parameter above).

Please note that changing the springdoc.swagger-ui.path and springdoc.api-docs.path configuration parameters is not supported, as they are hard-coded in the web application security filter chain to be accessible without any authentication.

One can disable the deployment of the Swagger UI web application by setting the springdoc.api-docs.enabled configuration parameter to false.

See here and here for additional information on the configuration.

Authentication

Access tokens

As a user, one can create and manage access tokens in the RDepot web UI (section “Access tokens”, under “Settings”). To create a new access token, click on the blue create button in the top right corner, give it a name and the number of days it should stay active. After creation, the value of the access token will be shown only once so please copy this value and store it in a safe (i.e. encrypted) location. The access token will have the same permissions as your own user. If an access token has not expired but should not be used any longer, then the access token can be deleted by clicking the red delete button in the Actions column.

The access token can be used in HTTP requests to the API by using HTTP basic authentication with your username as the user-id and your access token value as the password.

OAuth 2.0

If the RDepot API is configured to use OAuth 2.0, then any access tokens from the configured provider should be accepted by the API.

Username and password

If the RDepot API is configured to use simple authentication, then the API does not directly allow username and password authentication for every request. Instead, a short-lived access token (JWT) can be generated by executing the following HTTP POST request:

curl 'http(s)://<rdepot-backend-public-url>/login' \
  -X POST \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{"login":"your-username","password":"your-password"}'

When executed successfully, the response will look like:

{"status": "SUCCESS","code": 200,"messageCode": null,"message": null,"data": {"token": "my-short-lived-access-token"}}

The returned short-lived access token can then be used as the bearer token in the “Authorization” request header (see RFC6750).

An RDepot administrator can configure the lifetime of these tokens via the api-token.lifetime property (5 minutes by default).

Searching using query parameters

This section contains more information on the query parameters that can be used when using the API resources for searching. Each section describes a different type of resource within RDepot and the specific query parameters that are useful in that case.

Packages

Package Maintainers

Repositories

Repository Maintainers

Users

Submissions

Newsfeed Events

Access Tokens