API documentation out of date

Troubleshooting
2

I just talked to @jwilander on the community chat (thanks for taking all that time!) and so I’ve got a followup to my own post.

There are three explanations that cover some of the issues I raised:

  • Documentation Staleness: Yes, the documentation is out of date. There are a number of parameters that are returned by a server that are not documented, and those are being added.

  • “true” vs true: The return type of useAutomaticTimezone being a string instead of a boolean is a design flaw, but “working as designed”, and the documentation is being updated to reflect the actual return type.

  • Restricted Values: Some fields are only returned when the requesting user is authorized to see them (e.g. a user requesting data about themselves, or an admin requesting data), however these are not noted in the documentation.

As a result of our conversation there is already a PR addressing the first two issues, and partially addressing the third.

There are some issues still outstanding, and I’m planning to open GitHub Issues covering them, and will possibly be submitting some PRs to help address them (if I can find the time).

  1. The above PR only partially addresses the restricted values issue. First, it only references the problem for this one endpoint, while surely there are other endpoints where there are similarly restricted values. Second, it does not exhaustively identify which values have access restrictions.

  2. Some values are not returned if they are empty, false, or 0 (zero). But this behaviour isn’t consistently applied, and only affects some values, not all. This behaviour also needs to be documented somewhere.

  3. The combination of 1 and 2 means that the meaning of the API not returning a value is ambiguous, which is a problem of its own. Client code will need to guess about whether an omitted value is falsy, or whehter it actually has a value that the code isn’t able to retrieve.

  4. It’s not entirely clear to me that there aren’t other reasons why a value might not be returned. For example, what if a value applies to a feature that the server license doesn’t support? The fact that documenting this hasn’t been a priority, combined with item 2 being inconsistently applied, make it hard to trust that there aren’t other reasons for values being optional hiding in the code somewhere.