dump-things-service/docs/endpoints.rst

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.

.. contents:: Endpoint overview
   :local:
   :depth: 1


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.


.. _dump-things-pyclient: https://pypi.org/project/dump-things-pyclient/

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**:

  .. code-block:: json

     {
       "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:

.. code-block:: json

   {
     "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:

.. code-block:: json

   {
     "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
:doc:`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 :doc:`commands`).


Collections
^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 10 30 60

   * - 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 :ref:`config_file`), but has an additional ``name`` attribute that
specifies the name of the collection that should be created or updated.

When a collection is deleted via ``DELETE /collections/<name>``, the data that
is stored in storage root is **not** deleted. The collection information is
just removed from the internal configuration database. If a collection is
recreated with identical backend configurations, the data in the storage root
can be accessed again.

Tokens
^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 10 30 60

   * - 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 :ref:`config_file`), 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

Note: tokens that are accessible via the `/tokens`-endpoint are stored in the
internal configuration database. They can be used for authentication and if the
authentication source `config` (which is the default, if no authentication
source is defined for a collection) is configured. But tokens are only one way
to authenticate with the service, For example, Forgejo-authentication sources
can be used to authenticate via tokens and teams of a forgejo instance. That
means, to get the complete overview over authentication options for a
collection, the authentication source configuration of the collection has be be
taken into account.


Admin Tokens
^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 10 30 60

   * - 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 :ref:`config_file`), 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