Table of Contents
On this page

API Evolution pattern

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 entire endpoint or a single method 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.

Both headers are independent, you can use them separately.

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

Marking an entire endpoint as deprecated

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

...
#[ResourceDeprecation(
    sunset: '2038-01-01',
    link: 'https://docs.dotkernel.org/api-documentation/v6/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 entire / (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/v6/tutorials/api-evolution/;rel="sunset";type="text/html"
Vary: Origin

Marking a method as deprecated

Since version 6, in Dotkernel API each handler is PSR-15 middleware responsible for handling a single request method. This means that each resource operation will have its own handler class. Therefore, MethodDeprecation no longer has a class method to attach to. Instead, you should use the ResourceDeprecation attribute on the handler class.

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 was provided and are Link related parts.