check24/apitk-deprecation-bundle

This bundle provides deprecation functionality for RESTful APIs.

3.0.0 2021-11-09 12:00 UTC

Requires

• php: ^7.4 || ^8.0
• check24/apitk-common-bundle: ^2.2 || ^3.0
• check24/apitk-header-bundle: ^2.2 || ^3.0
• doctrine/annotations: ^1.6
• nelmio/api-doc-bundle: ^3.2
• sensio/framework-extra-bundle: ^5.1 || ^6.0
• symfony/config: >= 5.3 <6.0
• symfony/dependency-injection: >= 5.3 <6.0
• symfony/framework-bundle: >= 5.3 <6.0
• symfony/http-kernel: >= 5.3 <6.0

Requires (Dev)

• captainhook/captainhook: ^5.0
• captainhook/plugin-composer: ^5.1
• friendsofphp/php-cs-fixer: ^2.12
• phpmd/phpmd: ^2.6
• phpstan/phpstan: ^0.12

MIT

• Michael Wolf

README

Overview

This bundle enables you to mark API endpoints as deprecated and inform the client about that.

Installation

Install the package via composer:

composer require check24/apitk-deprecation-bundle

Usage

Deprecations

You can mark actions as deprecated so developers can notice that they have to update their API call to a newer version or to use a whole other endpoint.

use Shopping\ApiTKDeprecationBundle\Annotation\Deprecated;

/**
 * Returns the users in the system.
 *
 * @Rest\Get("/v2/users")
 * @Rest\View()
 *
 * @Deprecated(removedAfter="2018-10-09", since="2018-07-01", description="use /v3/users instead")
 
 * @param User[] $users
 * @return User[]
 */

A notice is displayed inside the swagger documentation and a new response header x-apitk-deprecated: use /v3/users instead, x-apitk-deprecated-removed-at: 2018-10-09 (if a date was set), x-apitk-deprecated-since: 2018-07-01 (if a date was set) will be sent to the client.

All annotation arguments are optional, so feel free to use @Deprecated only. In this case all clients will receive a x-apitk-deprecated: deprecated response header. The header's value may be overridden by providing the description argument as shown above.

If you want to hide a certain endpoint from the docs, use the hideFromDocs=true parameter in the Deprecated annotation. The corresponding action then will not be shown.

Class annotations

Since Version 1.0.6, it's possible to put @Deprecated annotations on a Controller's class to mark all containing endpoints as deprecated.
Please keep in mind that method annotations always override class annotations completely. No merging or whatsoever will be performed. When a controller class has a @Deprecated annotation, it's impossible to mark one or more methods of the controller as non-deprecated.

Deprecation Logging

Since version 2.0.0, the apitk-deprecation-bundle will throw E_USER_DEPRECATED errors when a deprecated endpoint is called. This is useful when you're using APM tools like NewRelic and would like to be notified when deprecated endpoints are called.

Deprecation logging is active by default. You may deactivate it globally by creating a config/packages/apitk_deprecation.yaml containing:

apitk_deprecation:
  trigger_deprecations: false # default: true

You can also activate/deactivate deprecation logging for specific endpoints only:

/**
 * Always log deprecations for this route or class, ignoring global settings:
 * @Deprecated(description="use /v3/users instead", triggerDeprecation=true)
 * 
 * Never log deprecations for this route or class, ignoring global settings:
 * @Deprecated(description="use /v3/users instead", triggerDeprecation=false)
 * ...
 */