Document ability to modify collections via API #215

New issue

Open

opened 2026-06-23 06:41:17 +00:00 by mih · 3 comments

mih commented

2026-06-23 06:41:17 +00:00

Owner

It should be documented how that is possible. My current understanding is that one needs to maintain a "shadow configuration" of a collection elsewhere, and delete and recreate a collection with adjusted configuration. This would be fairly complex and error prone.

At minimum there should be a way to retrieve the effective configuration for a collection, in order to alter that and be able to make an "incremental" change, without having to maintain editable configuration records in parallel.

Per personal communication: it is presently not possible to "update" a collection (add an audit backend, change tags, change inbox location, etc). I'd argue that it is not uncommon to have to make adjustement at some point. It should be documented how that is possible. My current understanding is that one needs to maintain a "shadow configuration" of a collection elsewhere, and delete and recreate a collection with adjusted configuration. This would be fairly complex and error prone. At minimum there should be a way to retrieve the effective configuration for a collection, in order to alter that and be able to make an "incremental" change, without having to maintain editable configuration records in parallel.

cmo commented

2026-06-23 07:06:52 +00:00

Owner

That's a good point. Currently, the configuration can be read by GET /collection, GET /tokens, GET /admin_tokens. The output is currently JSON, which can be used in POST /collections, POST /tokens, and POST /admin_tokens respectively.

The JSON object can be edited and POST-ed to create a modified configuration (it could also be used to create an identical configuration on another server). Because there is currently no PATCH-method support, POST-ing an updated configuration requires to DELETE the respective configuration first.

So an incremental update currently requires:

GET-ing the configuration of an entity (collection, token, or admin_token)
Editing the JSON object
DELETE-ing the respective entity
POST-ing the modified JSON-object

I will add:

support for PUT-method in the endpoints /collections, /tokens, /admin_tokens.
a GET-method that support to fetch the configuration of all tokens, collections, and admin-tokens (admin tokens are only available in hashed representation).

This will support incremental updates by reading the configuration from the server, editing it, and PUT-ing it.

The configuration object format is still JSON. To support "native" YAML-based configuration handling, I will add:

YAML input format for the POST-method of endpoints /collections, /tokens, /admin_tokens
YAML output format for the GET-method of endpoints /collections, /tokens, /admin_tokens

dump-things-upload-config should be amended to support JSON and YAML input formats, as well as support for uploading individual collections, tokens, or admin_tokens instead of complete configurations.

That's a good point. Currently, the configuration can be read by `GET /collection`, `GET /tokens`, `GET /admin_tokens`. The output is currently JSON, which can be used in `POST /collections`, `POST /tokens`, and `POST /admin_tokens` respectively. The JSON object can be edited and POST-ed to create a modified configuration (it could also be used to create an identical configuration on another server). Because there is currently no PATCH-method support, POST-ing an updated configuration requires to DELETE the respective configuration first. So an incremental update currently requires: 1. GET-ing the configuration of an entity (collection, token, or admin_token) 2. Editing the JSON object 3. DELETE-ing the respective entity 4. POST-ing the modified JSON-object I will add: - support for PUT-method in the endpoints `/collections`, `/tokens`, `/admin_tokens`. - a GET-method that support to fetch the configuration of all tokens, collections, and admin-tokens (admin tokens are only available in hashed representation). This will support incremental updates by reading the configuration from the server, editing it, and PUT-ing it. The configuration object format is still JSON. To support "native" YAML-based configuration handling, I will add: - YAML input format for the POST-method of endpoints `/collections`, `/tokens`, `/admin_tokens` - YAML output format for the GET-method of endpoints `/collections`, `/tokens`, `/admin_tokens` `dump-things-upload-config` should be amended to support JSON and YAML input formats, as well as support for uploading individual collections, tokens, or admin_tokens instead of complete configurations.

mih commented

2026-06-23 12:24:55 +00:00

Author

Owner

This sounds good!

I am not sure what the motivation for YAML support is. As far as I am concerned, this only plays a role in the configuration files that are a thing of the past. Any client can easily convert JSON to YAML (and back, if needed). No need to bloat the implementation, IMHO

This sounds good! I am not sure what the motivation for YAML support is. As far as I am concerned, this only plays a role in the configuration files that are a thing of the past. Any client can easily convert JSON to YAML (and back, if needed). No need to bloat the implementation, IMHO

cmo commented

2026-06-23 13:36:26 +00:00

Owner

I am happy with leaving YAML conversions to the client.

cmo referenced this issue

2026-06-24 06:48:19 +00:00

Support configuration update via PUT method #220