Central API docs: changelog per endpoint

Ideas
1

What high-level problem are you trying to solve?

As a maintainer of an API wrapper, or as a consumer of data via the API, I have to periodically review my implementation against API changes.

Especially API wrappers may want to support different ODK Central versions and toggle functionality for new/changed/removed API parameters according to ODK Central version.

The high-level Changelog - ODK Docs is wonderful for an end-to-end review/upgrade.

When I work on an individual endpoint, I would love to have all relevant changes listed in place.

Any ideas on how ODK could help you solve it?

If (and only if) feasible and maintainable, add per-endpoint changelogs to the respective endpoint’s docs.

Upload any helpful links, sketches, and videos.

Kubernetes v1.34 Spec: ConfigMap is a great example of per-endpoint changelogs.
However, the way these docs are produced (aptakube/kubespec.dev: Kubernetes Spec Explorer) may not lend itself to how ODK docs are built. I may be wise to weigh maintenance footprint of per-endpoint changelogs against the added benefit of API consumers.

1 Like
2

But we also will want the toplevel overview as we have now.

For you, would you be happy if we’d just mention, per endpoint, the releases in which any mutation has taken place? Then you can quickly verify if you need to read up on changes. If so, you’ll find the changes up top where we have them now. If we use some structure to list these releases, you might even automate things by parsing the api.yaml; you could make a gadget that goes “ping!” when there’s a change to any endpoint.