Deprecation and sunset middleware?

[gavinsykes]

Greetings all! 👋

I'm working on an application where the topic of deprecation has been mentioned (by me, admittedly) for some of our endpoints, and that has led me down the path of, well, just how do you deprecate an endpoint?

A bit of research online suggests that there aren't really any official standards, though just last month an IETF proposal was published to standardise the addition of a Deprecation header. With that in mind, I have started work on a simple way of signifying deprecation on your endpoints.

https://www.ietf.org/archive/id/draft-ietf-httpapi-deprecation-header-05.html

Middlewares

This is plainly in the territory of middlewares, so I have created 3 of them in the \Illuminate\Http\Middleware namespace: Deprecation, Sunset, and Link.

Deprecation

To mark an endpoint as deprecated, I would like to just be able to do the below:

Route::get('/endpoint')->deprecation();

Same for a group of endpoints, e.g.:

Route::deprecation()->group('/v1', function () {
    // Deprecated routes
});

As it is right now, this will add a middleware that adds a Deprecation header with a value of 'true'. (Because the header is Deprecation, I have opted to have the method name and middleware match that, rather than ->deprecated().

Sunset

Deprecation eventually leads to sunsetting, for which I'm aiming for a similar syntax e.g.

Route::get('/endpoint')->sunset('2024-09-24T00:00:00Z');

Route::sunset('2024-09-24T00:00:00Z')->group('/v1', function () {
    // Sunset routes
});

Once we are past the sunset date, I believe we should automatically return a 410 status code.

Sunsetting raises another question: should this middleware automatically add the Deprecation header also? I am inclined to say yes.

Either way, it will add a Sunset header with the formatted date-time Tue, 24 Sep 2024 00:00:00 UTC.

Link

When sunsetting, you may want to link your users to the replacement route (although there may not always be one). Make this accept either a relative path or an absolute URL.

Route::get('/endpoint')->sunset('2024-09-24T00:00:00Z')->link('https://example.com/new-endpoint');

Route::sunset('2024-09-24T00:00:00Z')->group('/v1', function () {
    Route::get('/an-endpoint')->link('/v2/a-new-endpoint');
    Route::get('/another-endpoint')->link('/v2/another-new-endpoint');
});

I'd love to hear the community's thoughts on these, and if they're worth adding in to the framework!

[shaedrich]

Wouldn't it be better to pass the link as a second parameter to sunset() or even as an array or object?

[henzeb]

Or a routename...

[shaedrich]

Or plaintext or other information

[gavinsykes]

I did consider that, however if you want to sunset a group of routes you'd then 'link' that whole group to the same new endpoint which probably wouldn't be wanted.

@henzeb yes, I hadn't actually considered a routename!

[algorhythm]

Have a look at this package: https://github.com/jobilla/deprecated-routes-middleware