api-deprecationlisted

# API deprecation Removing API surface breaks whoever depends on it, and for public APIs you often cannot see or contact all of them. Deprecation is the process that gets consumers moved off before you remove, through clear signals, measured usage, and a timeline long enough to migrate but firm enough to actually end. ## Method 1. **Signal deprecation in-band.** `Deprecation` and `Sunset` HTTP headers (RFC standards) on responses from deprecated endpoints, `@deprecated` in schemas (GraphQL, proto: see graphql-schema-design, grpc-services), and deprecation notices in docs (see api-reference-docs): so consumers discover the deprecation programmatically and in documentation, not by surprise when it breaks. The signal reaches the machine and the developer. 2. **Measure who still uses it.** Track usage of the deprecated surface by consumer (see observability, api- versioning's usage tracking): you cannot end a deprecation you cannot measure, because you never know if anyone still depends on it. Usage data tells you who to contact and when it is safe to remove. 3. **Provide the migration path before deprecating.** The replacement (new endpoint, new field, new version) exists and works, with a clear migration guide (what to change, with examples: see tutorial-writing, changelog-writing): deprecating without a migration path is just breaking with extra notice. Consumers need somewhere to go before you tell them to leave. 4. **S