Apitk Deprecation Bundle Laravel Package

Product Decisions This Supports

• API Versioning & Migration Strategy: Enables a structured, phased deprecation process for legacy API endpoints, reducing breaking changes and easing client transitions.
• Developer Experience (DX): Provides clear, automated documentation and headers to guide external developers toward newer endpoints, reducing support overhead.
• Compliance & Governance: Supports regulatory or internal policies requiring explicit deprecation timelines (e.g., GDPR, internal API lifecycle standards).
• Roadmap Execution: Accelerates sunset plans for deprecated APIs by embedding deprecation logic directly into the codebase, reducing manual tracking.
• Build vs. Buy: Avoids reinventing deprecation infrastructure (e.g., custom middleware, documentation tools) when existing solutions fit the stack.
• Use Cases:
  • Migrating from /v1/ to /v2/ endpoints.
  • Phasing out experimental or low-usage APIs.
  • Aligning with third-party API providers’ deprecation policies.

When to Consider This Package

• Adopt When:

  • Your API has versioned endpoints (e.g., /v1/, /v2/) and needs a standardized way to deprecate them.
  • You use Symfony/RESTful APIs with annotations (e.g., @Rest\Get) and Swagger/OpenAPI for documentation.
  • Your team lacks a centralized deprecation tracking system (e.g., Jira tickets, spreadsheets).
  • You want automated client notifications (headers) without manual middleware or documentation updates.
  • Your API has low-to-moderate complexity (not suitable for highly dynamic or microservice-heavy architectures).

• Look Elsewhere If:

  • You need runtime enforcement (e.g., blocking deprecated endpoints after a deadline) → Use middleware like nelmio/api-doc-bundle or custom logic.
  • Your API is not annotation-driven (e.g., uses XML configs, YAML, or pure PHP classes).
  • You require granular deprecation analytics (e.g., tracking client adoption rates) → Consider tools like Postman Monitoring or API Gateway solutions.
  • Your stack is non-PHP/Laravel (e.g., Node.js, Go, Python).
  • You need deprecation for non-REST resources (e.g., GraphQL, WebSockets) → Explore domain-specific tools.
  • The package’s last release (2021) is a concern for long-term maintenance → Evaluate alternatives like api-platform/core for modern PHP stacks.

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

*"This package streamlines our API deprecation process, reducing technical debt and support costs. By automatically flagging outdated endpoints in documentation and responses, we’ll:

• Accelerate migrations to newer APIs (e.g., /v3/), improving performance and features.
• Cut developer support overhead by 30%+ with clear, machine-readable deprecation notices.
• Future-proof our APIs with compliance-ready timelines, avoiding last-minute rush fixes.
• Leverage existing tools (Symfony/Swagger) without new infrastructure costs. Think of it as ‘autopilot for API sunsets’—saving time and headaches while keeping clients on the latest versions."

For Engineering/Tech Leads:

*"This lightweight bundle solves a common pain point: manually tracking and communicating API deprecations. Here’s why it’s a win:

• Zero Boilerplate: Adds @Deprecated annotations to existing REST controllers—no middleware or docs updates needed.
• Swagger Integration: Deprecated endpoints auto-hide or show warnings in OpenAPI docs, keeping clients informed.
• Client-Friendly Headers: Returns x-apitk-deprecated headers with migration paths (e.g., use /v3/users).
• Flexible Timelines: Set since/removedAfter dates to align with roadmaps or regulatory deadlines.
• Low Risk: MIT-licensed, PHP 7.4+ compatible, and battle-tested in Symfony ecosystems. Downside: Last updated in 2021, but the core logic is stable. If maintenance is a blocker, we can fork or pair it with a modern alternative like API Platform."*

For Developers:

*"If you’re tired of:

• Forgetting to update Swagger docs when deprecating endpoints.
• Writing custom middleware for deprecation headers.
• Explaining to clients why /v1/ ‘still works’ but isn’t supported. …this bundle does it all with one annotation:

@Deprecated(since="2024-01-01", description="Use /v3/orders", hideFromDocs=true)

Pros: ✅ Works with existing @Rest\* annotations. ✅ Adds headers like x-apitk-deprecated: Use /v3/orders. ✅ Hides deprecated endpoints from Swagger with hideFromDocs. ✅ Optional removedAfter date for enforcement planning. Cons: ⚠️ No runtime blocking (endpoints still respond). ⚠️ Last release was 2021 (but the pattern is solid). Want to try it? composer require check24/apitk-deprecation-bundle—it’s a 10-minute setup."