Documenting API Endpoint Deprecation: the Art of Planning Ahead
As a freelance software technical writer, I usually spend between half and a third of my time to care for API documentation, depending on the project and the company I am working for.
This can go from testing endpoints one by one to adjusting the endpoint classification in the documentation, enriching endpoint descriptions, renaming the endpoints to be understood by human beings, enriching parameter's descriptions, writing changelog posts, writing error messages, anticipating changes coming in the next version of the API, writing API guides, etc.

APIs are so critical to business growth those days, they usually evolve fast, which implies a constant stream of new endpoints to document as well as ancient endpoints being deprecated. Deprecating an endpoint means it will stop working in a close future, so the users need to be redirected to another way to perform the same task.
Why deprecate?
What does an API have to do to be punished that way?
There are several reasons for deprecating endpoints, which include but are not limited to:
The process of API Versioning (and Deprecating)
Deprecation are rarely discussed in isolation: they are part of the API roadmap and versioning plan, just like the introduction of new endpoints or changes to existing ones.
"Versioning is always a compromise between improving developer experience and the additional burden of maintaining old versions." - Brandur Leach, talking about Stripe API versioning.
Every company has its own process, but it usually follows those general steps:

How to Document Deprecations
Show the Deprecation Timeline
Craft a release note to be sent and published in the documentation, as well as a "deprecation" page for the documentation that lists all the coming changes, and especially clarifies the dates at which each endpoint will be fully deprecated.
The content needs to be reviewed and validated by the API team (if any), and/or by Product, before publication, so it is wise to start working on those content as soon as the list of deprecated endpoints is available.
A good example of a Deprecation page would be this one (from OpenAI). It gives general information about deprecation as well as provide a full 'Deprecation history' archive. I would recommend having this full history published and visible at all time.
You can also check this Deprecation release note example from Salesforce here. It provides a list of all versions affected by the change and has a "who, why, how" interesting section.
Publish Migration guide(s)
Write migration guides if there are new alternatives to the deprecated endpoints.
This will ensure that users can transition smoothly to new endpoints without any service interruption. If there will be no alternative provided, this needs to be stated in the documentation in a very clear manner, explaining why (business pivot, technical issue, etc.).
The guides need to be published long enough before the actual deprecation to give time to users to adjust. Don't be afraid to be proactive with emailing, either.
Update the Open API Spec
The Open API Spec could always use a check to make sure the mention "deprecated" is present where it should be.
This is usually a 'deprecated
' property added to the endpoint, set as 'true
'. It is useful to mention the coming deprecation in the endpoint description as well.
paths:
/example:
get:
summary: Fetch an example resource
description: This endpoint retrieves an example resource. It is deprecated and will be removed in the next version.
deprecated: true
Check for Deprecation Notices within the code
Developers often add warnings into the code of the API, which will display a deprecation notice in the header of the request (for REST API). As a technical writer, you can always ask if this will be implemented or not (it is usually a good practice), and if so, it can be mentioned in the documentation as well.
Those notices are important as they have more chances to be visible to developers handling API requests than traditional emails (but you should still do both).
The Sunset Header (RFC 8594)
The Sunset HTTP response header field allows a server to communicate the fact that a resource is expected to become unresponsive at a specific point in time. The Sunset header contains a single timestamp which advertises the point in time when the resource is expected to become unresponsive.
The Sunset Header is a standardized way to announce deprecation, which is one of the most efficient ways to proceed.
HTTP/1.1 200 OK
Sunset: Sat, 01 Jan 2024 00:00:00 GMT
The Deprecated directive (for GraphQL)
For GraphQL APIs, it is possible to use the @deprecated
directive in the schema to mark fields or queries as deprecated, optionally including a message.
type MyType {
id: ID!
oldField: String @deprecated(reason: "oldField is deprecated. Use newField instead.")
newField: String
deprecatedField: String @deprecated
}
Deprecation notice in the response
Independently of the header, developers can also add a deprecation warning in the response body of the HTTP request, saying the endpoint will be deprecated soon or is already deprecated.
As a technical writer, you can give it a test, and mention it to the technical teams if you see those are missing. You can also contribute to crafting the warning messages so they are standardized across all channels.
{
"data": {...},
"warnings": [
{
"code": "DEPRECATED_ENDPOINT",
"message": "This endpoint is deprecated and will be removed on 2024-01-01. Please use /new-endpoint instead."
}
]
}
So, what's the best way to proceed?
The best course of action is definitely to combine all of the above:
Working on a release note in advance and sending it by email several times as the deadline approaches (once way early, once a month before sunsetting, and a final warning a week before)
Having a deprecation timeline page in the documentation that is easy to find (emails can point towards it for more details) and that remains there at all times,
Publishing migration guides in advance, providing users with alternative options to perform the task they need to perform,
Having warnings embedded in the API code through the Sunset Header (for REST APIs) and using the @Deprecated directive for GraphQL APIs,
Once the endpoints are deprecated:
Marking those endpoints as deprecated in the Open API Spec,
Having warnings in the JSON responses stating the endpoint is deprecated,
Adding links to the relevant migration guides and/or alternative endpoints in the Open API spec endpoint description.
Finally, I would consider waiting on deleting the deprecated endpoints code once they are officially deprecated (I know, its hard). But there might always be a few clients relying on those who missed the warnings! Having a backup for those guys might come handy, even if it is just to delay the sunsetting of a few months.

Last updated