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 may stop responding and where the change is documented.

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 will potentially become unresponsive.

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

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.

FAQ

Q: What do the Sunset and Link headers mean?

A: Sunset is the date on which the deprecated resource may stop responding; 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.

Q: What if the Sunset date is invalid?

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

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.

Table of Contents

On this page