How do you know it is safe to remove a field from a public API, and what would you have needed to build to know that?

What is being tested

Whether you recognise that the constraint on deprecation is information, not policy, and that the information must have been collected in advance.

The reasoning

Removing a field is a one-line change. Knowing who depends on it is the entire problem, and for a public API the consumers include automation, scripts, integrations built by people who have left, and clients you cannot contact.

The only reliable answer is measurement: which consumers requested which fields, over a window long enough to catch infrequent usage. That window matters — a monthly reconciliation job or a quarterly report will not appear in seven days of data, and those are exactly the integrations whose breakage is most damaging.

This instrumentation cannot be added retroactively. If it does not exist, you can start collecting today and wait, which is the honest answer and usually an unwelcome one.

Why the other options fail

Searching your own codebase tells you about your consumers, not theirs. For a public API this is almost irrelevant.

A changelog entry and 30 days is a common practice and not evidence. It tells you that you announced it, not that anyone read it or could act on it in the time given.

A major version bump avoids breaking clients pinned to the old version and does nothing about those who follow the latest. It also assumes consumers upgrade deliberately, which many do not — and it leaves you maintaining both versions, which is a cost, not a solution.

The full deprecation sequence

1. Instrument per-consumer field usage. Prerequisite for everything else.
2. Announce with a date, and contact the identifiable users directly.
3. Return deprecation headers, so it appears in the consumer's own logs where their engineers will see it.
4. Brownout — brief scheduled error periods — to surface non-responders while there is time.
5. Withdraw, with a documented exception process.
6. Reserve the name or identifier so it is never reused.

The pattern from developer platforms

Platforms like GitHub demonstrate the discipline at scale: documented deprecation policy, long notice periods, in-band warning headers, and a strong bias toward additive change because the consumer base is effectively unbounded and includes automation nobody can reach.

That bias is the strategic conclusion. When you cannot enumerate or contact your consumers, the cheapest policy is one that rarely requires removal — additive-only evolution, with deprecated fields carried indefinitely. Schema tidiness is not worth the cost of a migration you cannot coordinate.

What a strong answer adds

Distinguishing internal from external. Full versioning and deprecation ceremony for an internal API with three known callers is over-engineering; you update the three callers. The ceremony exists because you cannot upgrade the other side, and where you can, you should.