Tell an API caller what the remaining endpoints take - #738
Open
blaipr wants to merge 1 commit into
Open
Conversation
The six families that still had no help class — authorisations, notifications, profiles, the event log, custom fields and public links — answered a missing parameter with nothing but 'Wrong parameters'. Every family now names what it accepts and which of those it requires, as the account, category, client, tag, group and user ones do. Each list is read off its own controller rather than assumed, because a help text that lies about what is required is worse than none. Three places where the source did not fit the pattern, and what was done about them: a token's password is genuinely optional, so it says so; a public link's typeId is fixed by the controller and is not a caller's parameter at all, so it is left out; and public links have no edit endpoint, so there is no edit help. Each family's required-parameters test now asserts the answer names the parameters. The event log has none to assert — neither of its actions requires anything.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The six API families that still had no help class — authorisations, notifications, profiles, the event log, custom fields and public links — answered a missing parameter with nothing but
Wrong parameters. Each now names what it accepts and which of those it requires, as the account, category, client, tag, group and user families do.Follows #737, which did the same for the user endpoints; this closes the gap rather than leaving five more instances of it.
Read, not assumed
Each list comes from its own controller. A help text that lies about what is required is worse than none, so three places where the source did not fit the pattern are handled explicitly:
getParamRawwith no required flag — a token can be created with a null hash), so the help says optional;typeIdis fixed by the controller and is not a caller parameter at all, so it is left out entirely rather than documented as something to send;edit()help.Testing
Each family's required-parameters test now asserts the answer names the parameters. The event log has none to assert — neither of its two actions requires anything — so it gets the help class and no test change.
API integration tests: 227 green. PHPStan and PHPCS clean.
One note on verifying this: the suite has to be run with nothing else touching the database. A first run reported five routing failures that vanished on a clean run — two processes were sharing the fixture database, not a real fault.