HTTP Endpoints

All endpoints are accessible via the interactive Swagger UI at /docs after starting the service.

Most endpoints that operate on records require a collection name and a valid token supplied in the X-DumpThings-Token HTTP header.

Note: The package dump-things-pyclient provides client support for the service. A Python API makes the endpoints available to Python code. The command line tool dtc makes the endpoints available in the shell.

User Endpoints 

Store a Record

POST /<collection>/record/<class>

Stores an object of type <class> (defined in the collection schema) in the incoming area for the authenticated token’s zone.

Requires: write permission (WRITE_INCOMING or higher).
Query parameters:
- format: json (default) or ttl (Turtle RDF).
- add_submission_tag: if true the server adds automated submitter-ID and submission-time annotations. Default: false.
Content-Type: application/json for JSON; text/turtle for Turtle.
Returns: list of all stored records (may contain more than one entry when the posted object contains inlined records).

Validate a Record

POST /<collection>/validate/record/<class>

Validates a record without storing it. Supports the same parameters as POST /<collection>/record/<class>.

Retrieve All Records of a Class

GET /<collection>/records/<class>

Returns all readable records of type <class> (and its subclasses). Records from the incoming zone take precedence over identical PIDs in the curated area.

Requires: read permission.
Query parameters:
- format: json (default) or ttl.
- matching: wildcard pattern for sqlite backends; % matches any characters (case-insensitive). Ignored by record_dir backends.

Retrieve All Records of a Class (Paginated)

GET /<collection>/records/p/<class>

Same as above but with pagination support.

Additional query parameters:
- page: page number (starting at 1).
- size: records per page (default: 50).

Response structure:

{
  "items": ["<record or ttl-string>"],
  "total": 123,
  "page": 1,
  "size": 50,
  "pages": 3
}

Retrieve All Records

GET /<collection>/records/

Returns all readable records of a collection regardless of class. Supports the same format and matching parameters.

Retrieve All Records (Paginated)

GET /<collection>/records/p/

Paginated version of the endpoint above; supports the same page and size parameters.

Retrieve a Single Record by PID

GET /<collection>/record?pid=<pid>

Retrieves the record with the given PID. If both the incoming zone and the curated area contain a record with the same PID, the incoming record is returned.

Query parameters:
- format: json (default) or ttl.

Delete a Record

DELETE /<collection>/record?pid=<pid>

Deletes the record with PID <pid> from the incoming area.

Requires: write permission.
Returns: true if the record was deleted, false otherwise.

Server Information

GET /server

Returns information about the running service:

{
  "version": "<service version>",
  "collections": [
    {
      "name": "collection_1",
      "schema": "https://example.org/schema.yaml",
      "classes": ["Thing", "Agent", "Person"]
    }
  ]
}

Maintenance Mode

POST /maintenance

Puts a collection into maintenance mode. In maintenance mode only tokens with curator privileges can access the collection.

Request body:

{
  "collection": "collection_1",
  "active": true
}

Curation Endpoints 

Curation endpoints allow direct read/write access to the curated area and all incoming zones (aka: inboxes). A CURATOR token is required.

Refer to the interactive API documentation at /docs on a running service for the full list of curation endpoints.

Administration Endpoints 

A Dump Things Service instance can be reconfigured at runtime via the administration endpoints. These endpoints allow to create, update, and delete collections, tokens, and admin tokens.

The service keeps an internal model of the configuration which can be modified by adding or removing elements via the administration endpoints (see Configuration for a more detailed description of the configuration model).

Note: all administration endpoints require an administrator token.

Currently the smallest units for updates are also collections, tokens, and admin tokens. That means, to update, for example, the authentication sources of an existing collection, a complete collection configuration with updated authentication sources has to be sent. The current collection configuration can be read via the GET /collections/<name> endpoint. Modifying an existing collection can therefore be implemented by reading the current collection configuration, modifying it, and sending it to the server via the PUT /collections/<name> endpoint. The same holds for tokens and admin tokens.

The commands dump-things-download-config and dump-things-upload-config support this workflow. dump-things-download-config downloads the current configuration from a server and stores it as configuration file. dump-things-upload-config reads a configuration file and invokes the API requests that are necessary to create the elements from the configuration file on a server (see Command-Line Tools).

Collections

Method	Path	Description
POST	`/collections`	Create a new collection ( .
GET	`/collections`	List all collections.
GET	`/collections/<name>`	Get information about a specific collection.
PUT	`/collections/<name>`	Update an existing collection.
DELETE	`/collections/<name>`	Remove a collection from the service state (data is not deleted).

The payload for POST /collections and PUT /collections is a JSON objects that corresponds to the collection configuration object (see Configuration File Structure), but has an additional name attribute that specifies the name of the collection that should be created or updated.

Tokens

Method	Path	Description
POST	`/tokens`	Create a new token.
GET	`/tokens`	List all tokens (including representations).
GET	`/tokens/<name>`	Get information about a specific token.
PUT	`/tokens`	Update an existing token.
DELETE	`/tokens/<name>`	Delete a token.

The payload for POST /tokens and PUT /tokens is a JSON objects that corresponds to the token configuration object (see Configuration File Structure), but has an additional name attribute that specifies the name of the token that should be created or updated.

If no representation is provided in the payload, the server generates a random token representation and returns it in the representation attribute of the response. If a representation is provided and hashed is True, the representation must be a valid token-hash, i.e, a sha256 hash of the plaintext-token in hexdigit format. The command dump-things-hash-token can be used to generate a valid token hash

Admin Tokens

Method	Path	Description
POST	`/admin_tokens`	Create a new admin token (representation must be a SHA-256 hash).
GET	`/admin_tokens`	List all admin tokens.
GET	`/admin_tokens/<name>`	Get information about a specific admin token.
PUT	`/admin_tokens`	Update an existing admin token.
DELETE	`/admin_tokens/<name>`	Delete an admin token.

The payload for POST /admin_tokens and PUT /admin_tokens is a JSON objects that corresponds to the admin token configuration object (see Configuration File Structure), but has an additional name attribute that specifies the name of the admin token that should be created or updated.

The representation attribute must be a valid token-hash, i.e, a sha256 hash of the plaintext-token in hexdigit format. The command dump-things-hash-token can be used to generate a valid token hash