# 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.

```php
...
#[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.

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

```shell
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](../upgrading/UPGRADE-7.2.md).

## 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](../flow/middleware-flow.md).

**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.
