More infromative/definitive POST collection API docs/examples #216

New issue

Open

opened 2026-06-23 07:02:18 +00:00 by mih · 1 comment

mih commented

2026-06-23 07:02:18 +00:00

Owner

At the moment, the structured record example that could be submitted is

{
  "default_token": "string",
  "curated": "string",
  "schema": "string",
  "incoming": "string",
  "backend": {
    "type": "record_dir+stl",
    "mapping_method": "digest-md5"
  },
  "auth_sources": [
    {
      "type": "config"
    }
  ],
  "audit_backends": [],
  "submission_tags": {
    "submitter_id_tag": "http://purl.obolibrary.org/obo/NCIT_C54269",
    "submission_time_tag": "http://semanticscience.org/resource/SIO_001083"
  },
  "use_classes": [],
  "ignore_classes": [],
  "name": "string"
}

This appears to be in no particular order. It is unclear what require parameters are. From trial an error I know that there are required parameters.

I do not know what is possible to present in this location, but some more information needs to be given. This could be a pointer to more complete docs, a sorting of required parameters first (or some other logical grouping) that is pointed out in the endpoint description.

At the moment, the structured record example that could be submitted is ```json { "default_token": "string", "curated": "string", "schema": "string", "incoming": "string", "backend": { "type": "record_dir+stl", "mapping_method": "digest-md5" }, "auth_sources": [ { "type": "config" } ], "audit_backends": [], "submission_tags": { "submitter_id_tag": "http://purl.obolibrary.org/obo/NCIT_C54269", "submission_time_tag": "http://semanticscience.org/resource/SIO_001083" }, "use_classes": [], "ignore_classes": [], "name": "string" } ``` This appears to be in no particular order. It is unclear what require parameters are. From trial an error I know that there are required parameters. I do not know what is possible to present in this location, but some more information needs to be given. This could be a pointer to more complete docs, a sorting of required parameters first (or some other logical grouping) that is pointed out in the endpoint description.

cmo commented

2026-06-23 08:17:03 +00:00

Owner

The documentation is sorely lacking. The current reference for the collection request is the class CollectionRequest in the file dump_things_service/collection_endpoints.py. Token- and admin_token-requests refer to their respective classes (README.md lists the classes and their locations in the endpoint descriptions).

That is not user-friendly. I will add structured documentation of the payload of configuration requests.

The documentation is sorely lacking. The current reference for the collection request is the class `CollectionRequest` in the file `dump_things_service/collection_endpoints.py`. Token- and admin_token-requests refer to their respective classes (`README.md` lists the classes and their locations in the endpoint descriptions). That is not user-friendly. I will add structured documentation of the payload of configuration requests.