Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ api-toolbox is configured in `config/api-toolbox.php`. Before hand-rolling any o
| Cheap re-fetches of a resource | `conditional` middleware (ETag, `304`) |
| Stop lost updates | the model implements `HasValidators` and is bound to the route, which adds `conditional` and `preconditions.required`: the first gives the `412`, the second only the `428` |
| A `PATCH` | `merge-patch` and `consumes:application/merge-patch+json`, which replaces the group's `consumes:` |
| Retire an endpoint | `#[Deprecation]` and `#[Sunset]` on the controller class; Kit answers `410` after the sunset date |
| Retire an endpoint | `#[Deprecation]` and `#[Sunset]` on the controller class; Kit answers `410` (`endpoint-sunset`) after the sunset date |
| Work that outlives the request | Async operations; switched off in the config, and turning it on adds a route to document |
| Signed webhooks | Message signatures; keys go in the config, never in code |

Expand Down
21 changes: 17 additions & 4 deletions app/Http/Middleware/RetireSunsetEndpoints.php
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,23 @@

namespace App\Http\Middleware;

use App\Problems\EndpointSunset;
use Closure;
use DateTimeImmutable;
use Illuminate\Http\Request;
use Illuminate\Routing\Route;
use JustSteveKing\Toolbox\Deprecation\Contracts\DeprecationSource;
use JustSteveKing\Toolbox\Deprecation\Notice;
use Symfony\Component\HttpFoundation\Response;

/**
* Answers 410 Gone once a route's #[Sunset] date has passed.
*
* RFC 8594 section 1 says a resource is expected to become unresponsive at its sunset. api-toolbox
* sends the Deprecation and Sunset headers; this enforces the date those headers announce.
* sends the Deprecation and Sunset headers; this enforces the date those headers announce. The
* problem is apiguide.dev's endpoint-sunset rather than plain gone: the interface was retired on
* purpose, so the fault is in the client's code, not its data, and the body says when and where to
* go instead, as that entry asks.
*/
final readonly class RetireSunsetEndpoints
{
Expand All @@ -31,11 +36,19 @@ public function handle(Request $request, Closure $next): Response
$route = $request->route();

if ($route instanceof Route) {
$sunsetAt = $this->deprecations->forRoute($route)?->sunsetAt;
$notice = $this->deprecations->forRoute($route);
$sunsetAt = $notice?->sunsetAt;

// Laravel's clock rather than the system's, so a test can travel past a sunset.
if ($sunsetAt instanceof DateTimeImmutable && $sunsetAt <= now()->toDateTimeImmutable()) {
abort(Response::HTTP_GONE, __('api.sunset.endpoint_unavailable'));
if ($notice instanceof Notice && $sunsetAt instanceof DateTimeImmutable && $sunsetAt <= now()->toDateTimeImmutable()) {
throw new EndpointSunset(
detail: __('api.sunset.endpoint_unavailable'),
extensions: array_filter([
'deprecatedAt' => $notice->deprecatedAt?->format(DATE_ATOM),
'sunsetAt' => $sunsetAt->format(DATE_ATOM),
'migrationGuide' => $notice->sunsetLink ?? $notice->deprecationLink,
], static fn(?string $value): bool => null !== $value),
);
}
}

Expand Down
16 changes: 16 additions & 0 deletions app/Problems/EndpointSunset.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?php

declare(strict_types=1);

namespace App\Problems;

use JustSteveKing\Toolbox\ProblemDetails\Attributes\ProblemType;
use JustSteveKing\Toolbox\ProblemDetails\ProblemException;
use JustSteveKing\Toolbox\Support\ApiGuide;

/**
* An endpoint called after its #[Sunset] date (apiguide.dev's endpoint-sunset). Thrown by
* RetireSunsetEndpoints, with deprecatedAt, sunsetAt and migrationGuide in the body.
*/
#[ProblemType(ApiGuide::ENDPOINT_SUNSET, title: 'Endpoint Sunset', status: 410)]
final class EndpointSunset extends ProblemException {}
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"license": "MIT",
"require": {
"php": "^8.5",
"juststeveking/api-toolbox": "^0.3.2",
"juststeveking/api-toolbox": "^0.3.3",
"laravel/framework": "^13.30",
"laravel/octane": "^2.21",
"laravel/sanctum": "^4.3",
Expand Down
14 changes: 7 additions & 7 deletions composer.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 5 additions & 1 deletion docs/http-standards.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,11 @@ plus `Link` headers pointing at the pages you named. Client tooling can warn on
has to read your changelog to find out.

When the sunset date passes, `RetireSunsetEndpoints` starts answering `410 Gone` as a problem,
still carrying both headers. You do not have to remember to delete the route on the day.
still carrying both headers. The problem's type is apiguide.dev's `endpoint-sunset` rather than
plain `gone`, so a client can tell a retired interface (a fault in its code) from a deleted record,
and the body says when and where to go instead: `deprecatedAt`, `sunsetAt`, and `migrationGuide`,
which is the `#[Sunset]` link, or the `#[Deprecation]` one without it. You do not have to remember
to delete the route on the day.

The attributes go on the controller class or its `__invoke` method. Closure routes have nowhere to
put them, so they cannot be deprecated this way.
Expand Down
11 changes: 9 additions & 2 deletions tests/Feature/DeprecationTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,12 @@
Route::middleware('api')->get($path, RetiredEndpoint::class);

$this->getJson($path)
->assertProblemType('https://apiguide.dev/errors/gone', 410)
->assertProblemType('https://apiguide.dev/errors/endpoint-sunset', 410)
->assertJsonPath('title', 'Endpoint Sunset')
->assertJsonPath('detail', __('api.sunset.endpoint_unavailable'))
->assertJsonPath('deprecatedAt', '2000-01-01T00:00:00+00:00')
->assertJsonPath('sunsetAt', '2001-01-01T00:00:00+00:00')
->assertJsonMissingPath('migrationGuide')
->assertDeprecated('2000-01-01T00:00:00Z')
->assertSunset('2001-01-01T00:00:00Z');
});
Expand All @@ -40,7 +44,10 @@

$this->travelTo(new DateTimeImmutable('2099-01-01T00:00:01Z'));

$this->getJson($path)->assertProblemType('https://apiguide.dev/errors/gone', 410);
// The sunset's link is where to go instead (apiguide.dev's endpoint-sunset asks for it).
$this->getJson($path)
->assertProblemType('https://apiguide.dev/errors/endpoint-sunset', 410)
->assertJsonPath('migrationGuide', 'https://docs.example.com/sunset-policy');
});

it('serves deprecated endpoints that have no sunset date', function (): void {
Expand Down
4 changes: 2 additions & 2 deletions vet.json
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,8 @@
"hash": "tree-v2:c5f332afdb641a8e51865f5fe4448a3c4c2d9ec959e76360003b5489525deaf6"
},
"juststeveking/api-toolbox": {
"version": "v0.3.2",
"hash": "tree-v2:922ab467587f40da7d9c80cc6e528ca53351d190c2388857cbf9569476231a97"
"version": "v0.3.3",
"hash": "tree-v2:9702f3be02ea51ac9774e538e51e6c06b902058440c22b41cbceeaf17e678d5a"
},
"laminas/laminas-diactoros": {
"version": "3.9.0",
Expand Down
Loading