Skip to content

A sunset endpoint answers apiguide.dev's endpoint-sunset - #27

Merged
JustSteveKing merged 2 commits into
mainfrom
feature/endpoint-sunset-problem
Oct 30, 2026
Merged

JustSteveKing merged 2 commits into
mainfrom
feature/endpoint-sunset-problem

Conversation

@JustSteveKing

@JustSteveKing JustSteveKing commented Oct 30, 2026 •

Copy link
Copy Markdown
Owner

After an endpoint's #[Sunset] date, RetireSunsetEndpoints answered 410 with the plain gone type, which also covers a deleted record. apiguide.dev now has endpoint-sunset for exactly this case: an interface retired on purpose after its sunset. It tells a client the fault is in its code rather than its data, and asks for the replacement in the body.

  • api-toolbox ^0.3.3, whose catalogue has the type (reviewed and trusted in Vet). It's its own commit.

  • App\Problems\EndpointSunset, made with php artisan make:api-problem EndpointSunset --apiguide=endpoint-sunset. It's Kit's first typed problem.

  • The 410 throws it, with the members apiguide.dev's entry shows:

    • deprecatedAt and sunsetAt, as ISO 8601;
    • migrationGuide, which is the #[Sunset] link, or the #[Deprecation] one without it.

    Absent values are left out. The Deprecation and Sunset headers still go with it.

  • Docs: docs/http-standards.md and the table in AGENTS.md say so.

Tests: the retired endpoint's 410 now asserts the type, title, detail and both dates, with no migrationGuide because it has no links. The clock-travel test asserts the type and that migrationGuide is the sunset link. Both fail on the old middleware. The full suite (166) passes, and Rector, PHPStan and Pint are clean.

A breaking change for any client that branched on gone for a sunset endpoint, so worth a line in the release notes.

Summary by CodeRabbit

  • Bug Fixes
    • Endpoints accessed on or after their sunset date now return a structured 410 Gone response with the endpoint-sunset problem type, rather than a plain 410.
    • Responses include deprecation and sunset dates, and provide a migration guide when one is available.
  • Documentation
    • Updated HTTP standards guidance to describe the response type, included details, and migration-guide behavior.

Reviewed and trusted in Vet by Steve. 0.3.3 brings the apiguide.dev
catalogue's endpoint-sunset type, which the next commit uses.
RetireSunsetEndpoints answered plain gone, which also fits a deleted
record. apiguide.dev now has endpoint-sunset for exactly this, an
interface retired on purpose, which tells a client the fault is in its
code and asks for the replacement in the body. The 410 throws the new
App\Problems\EndpointSunset (made with make:api-problem --apiguide)
carrying deprecatedAt, sunsetAt and migrationGuide, the #[Sunset] link
or else the #[Deprecation] one.
@coderabbitai

coderabbitai Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Caution

Review failed

The pull request is closed.

Walkthrough

The sunset middleware now throws an EndpointSunset problem with status 410 when a valid sunset date is at or before the current time. The response includes deprecation and sunset details, and selects the migration guide from the sunset link before the deprecation link.

Changes: Sunset response

Layer / File(s) Summary
Problem contract and middleware
app/Problems/EndpointSunset.php, app/Http/Middleware/RetireSunsetEndpoints.php, composer.json, vet.json
Adds the endpoint-sunset problem exception with status 410. The middleware raises it for a Notice with a DateTimeImmutable sunset date at or before the current time. The response includes localized detail and date fields, and selects sunsetLink before deprecationLink. The API toolbox dependency is updated to version 0.3.3.
Response tests and documentation
tests/Feature/DeprecationTest.php, docs/http-standards.md, AGENTS.md
Tests now check the problem type, title, dates, and migration-guide behavior. The documentation and retirement guidance describe the endpoint-sunset response and its fields.

Priority: Not assessed

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Possibly related PRs

  • JustSteveKing/kit#24: Changes the sunset-date clock comparison in the same middleware and adds a clock-travel test in the same feature-test file.
Merge Risk: Low · up to c8b51

The response change is mergeable with a small documentation correction: clients should not require optional response fields. Adding fallback coverage would improve regression protection.

Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@JustSteveKing JustSteveKing self-assigned this Oct 30, 2026
@JustSteveKing
JustSteveKing merged commit 9c06498 into main Oct 30, 2026
8 checks passed
@JustSteveKing
JustSteveKing deleted the feature/endpoint-sunset-problem branch October 30, 2026 09:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant