Skip to content

docs(15.9): use the snake_case field names of the admin API - #569

Merged
marevol merged 1 commit into
mainfrom
docs/admin-api-snake-case
Oct 4, 2026
Merged

marevol merged 1 commit into
mainfrom
docs/admin-api-snake-case

Conversation

@marevol

@marevol marevol commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Summary

The 15.9 admin REST API pages documented the JSON fields in camelCase. Fess maps admin API bodies with CAMEL_TO_LOWER_SNAKE, so the real request and response fields are snake_case. Sending camelCase makes only the multi-word fields fail as "required", e.g. scriptType instead of script_type.

This PR changes every documented JSON key in the request/response examples, field tables and curl examples to the name the API actually uses, in all 7 locales and in 15.9 only. Single-word names are unchanged. The names were taken from each ApiAdmin*Action and its Body/Form classes.

  • Some names deliberately stay camelCase, because they are not JSON body fields:
    • map keys (user/group attributes, log/storage lastModified/hashCode);
    • multipart upload fields (e.g. badWordFile).
  • Fess leaves null values out of responses, so the pages no longer say that ldap_admin_security_credentials and job_log_id come back as null.
  • Two heading underlines that were too short (ja and de boostdoc) are fixed.

Verification

  • tools/check_headings.py passes for all 7 locales.
  • docutils reports no new messages for the 161 changed files.
  • A Sphinx build shows the same warnings before and after.
  • The field names match across all locales.

The admin API maps JSON with CAMEL_TO_LOWER_SNAKE, so request bodies are
bound and responses are written with snake_case keys (script_type,
sort_order, version_no, ...). Sending the camelCase names shown in the
docs leaves every multi-word field unset. Rename the keys in the JSON
examples, field tables, curl examples and prose of every 15.9 admin API
page in all seven locales.

Keys that are map entries rather than bean fields keep their names: user
and group attributes (givenName, gidNumber, ...), the log and storage file
items (lastModified, hashCode), and the multipart upload parameters
(badWordFile, synonymFile, ...).

Responses omit null fields, so ldap_admin_security_credentials in the
general settings and job_log_id when job logging is off are now described
as absent instead of null.
@marevol marevol self-assigned this Oct 4, 2026
@marevol
marevol merged commit c2cc878 into main Oct 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant