Improve API docs about updating form metadata/config

Open
#2,289 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
Half a day
Newbie friendliness
55/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Domain
api, documentation

Research direction

The gap is in the 'Modifying a Form' section of the API docs at docs.getodk.org/central-api-form-management, which says only state can be changed. Find where that page's source lives, then add webformsEnabled to the list of modifiable fields. Check the state values against the user docs before linking to them. Done when the section lists every modifiable field and the state meanings or links are present; the payload does not say whether the maintainers want the meanings written out or just linked.

Written by the indexing model from the issue text.

Description

backend documentation

Filing an issue based on https://github.com/getodk/central-backend/pull/1966#discussion_r4279217761

The API docs about Modifying a Form seem to be missing a couple of things. The docs say:

It is currently possible to modify only one thing about a Form: its state

However, these days, it is also possible to modify webformsEnabled.

See the state Attribute in the Request documentation to the right to see the possible values and their meanings.

  1. I don't see any Request documentation to the right. That text may predate our moving the API docs to docs.getodk.org.
  2. I don't see that we document the meaning of each state and the differences between the states. I think we could consider linking to the user docs for this.
Dominant language
JavaScript
Stars
233
Forks
241
Avg merge
1d 22h
Merged PRs (30d)
13

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from getodk/central

All issues in getodk/central

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.