Prompt
Should I care about hidden APIs I didn't document?
Latest observation
Yes — if you’re asking from the perspective of an API provider, you should care a lot.
Hidden or undocumented APIs can create real problems because they often become:
- Unstable contracts: clients may depend on behavior you never intended to support.
- Security risks: undocumented endpoints, parameters, or methods can be easier to miss in reviews and monitoring.
- Maintenance burden: once someone discovers and uses them, changing them can break things unexpectedly.
- Support headaches: users may rely on features your docs don’t mention, making troubleshooting harder.
- Compliance/audit issues: “hidden” functionality can complicate governance and release reviews.
That said, you don’t necessarily need to treat every undocumented thing as a problem. A practical approach is:
-
Inventory what exists
Find undocumented endpoints, fields, flags, and behaviors. -
Decide whether they’re public or internal
- If public: document them or intentionally deprecate them.
- If internal: restrict access and make sure they’re not exposed accidentally.
-
Add tests and ownership
Hidden functionality should still have clear owners and automated coverage. -
Deprecate carefully
If something is already in use, give notice and migration paths before removal.
If you meant this from the consumer side instead, the answer is also yes: undocumented APIs can be useful, but you should treat them as fragile and unsupported.
If you want, I can also give you a risk-based checklist for deciding whether an undocumented API should be documented, deprecated, or removed.