API Evolution pattern

Summary

Dotkernel API lets you evolve endpoints without breaking existing consumers by marking a handler with the ResourceDeprecation attribute. The DeprecationMiddleware then adds Sunset and Link response headers, telling consumers when the resource will stop responding and where the change is documented. From the sunset date onwards the middleware no longer runs the handler and returns 410 Gone.

Details

API evolution: Updating an API while keeping it compatible for existing consumers by adding new features, fixing bugs, planning and removing outdated features.

How it works

In Dotkernel API we can mark an endpoint as deprecated using attributes on handlers. We use response headers to inform the consumers about the future changes by using two new headers:

Link - it's a link to the official documentation pointing out the changes that will take place.
Sunset - this header is a date, indicating when the deprecated resource becomes unavailable. From that date the endpoint returns 410 Gone.

The above headers are independent, so you can use them separately.

Make sure you have the DeprecationMiddleware:class added to your pipeline list. In our case it's config/pipeline.php.

Marking an endpoint as deprecated

When you want to mark a resource as deprecated, you have to use the ResourceDeprecation attribute.

...
#[ResourceDeprecation(
    sunset: '2038-01-01',
    link: 'https://docs.dotkernel.org/api-documentation/v7/tutorials/api-evolution/',
    deprecationReason: 'Resource deprecation example.',
    rel: 'sunset',
    type: 'text/html'
)]
class HomeHandler implements RequestHandlerInterface
{
}

In the example above, the ResourceDeprecation attribute is attached to the class, marking the / (home) endpoint as deprecated starting from 2038-01-01.

Running the following curl will print out the response headers where we can see the Sunset and Link headers.

curl --head -X GET http://0.0.0.0:8080 -H "Content-Type: application/json"

HTTP/1.1 200 OK
Host: 0.0.0.0:8080
Date: Mon, 24 Jun 2024 10:23:11 GMT
Connection: close
X-Powered-By: PHP/6.4.20
Content-Type: application/json
Permissions-Policy: interest-cohort=()
Sunset: 2038-01-01
Link: https://docs.dotkernel.org/api-documentation/v7/tutorials/api-evolution/;rel="sunset";type="text/html"
Vary: Origin

Version differences

In Dotkernel API 7.0 and 7.1, the GET / handler (GetIndexResourceHandler) carries this attribute as a live example, so the curl call above shows the Sunset and Link headers. In 7.2 the attribute is removed from that handler, so GET / returns no deprecation headers; the headers appear on the handlers you mark yourself.

Update to the latest Dotkernel API 7.x release to get the current behavior, see Upgrading from 7.1 to 7.2.

Notes

If Link or Sunset do not have a value they will not appear in the response headers.

Sunset has to be a valid date, otherwise it will throw an error.

Deprecations can only be attached to handler classes that implement RequestHandlerInterface.

The rel and type arguments are optional, they default to sunset and text/html if no value is provided and are Link related parts.

An operation's operationId is part of the contract too: clients generated from the OpenAPI document use it as the method name, so renaming it breaks them even if the route is unchanged.

FAQ

Q: What do the Sunset and Link headers mean?

A: Sunset is the date on which the deprecated resource stops responding and starts returning 410 Gone; Link points to documentation describing the change. They are independent, so either can be used alone.

Q: What do I need in place before deprecations work?

A: DeprecationMiddleware::class must be present in your pipeline — in the default project, config/pipeline.php. See Middleware flow.

Q: Can I deprecate a single method rather than a whole resource?

A: The ResourceDeprecation attribute is applied to the handler class, so the unit of deprecation is the handler. Since each handler serves one method and route, deprecating the handler deprecates that method.

Q: What happens if I leave Sunset or Link empty?

A: The corresponding header is simply omitted from the response. Without a Sunset date the endpoint never returns 410 Gone.

Q: What if the Sunset date is invalid?

A: It throws an error. The value has to be a valid date.

Q: What does the response look like once the sunset date has passed?

A: The handler is not run and the response is 410 Gone with the detail This resource is no longer available (sunset on <date>). The type field of the problem-details body holds the documentation URL: the attribute's link, or else the configured documentation_url.

Q: Are rel and type required?

A: No. They default to sunset and text/html, and both relate to the Link header.

Q: Which classes can carry a deprecation?

A: Only handler classes implementing RequestHandlerInterface.

Q: How do I check that the headers are being sent?

A: Request the endpoint with curl --head and inspect the response headers.

Q: Is renaming an operationId a breaking change?

A: Yes, for clients generated from the OpenAPI document, which use it as the method name. Treat it like a renamed field: keep the old name until its consumers have moved.

Table of Contents