versioning

[arhimede]

do we want to prepare it for versioning ?

[arhimede]

not classical versioning, but by using sunset header
evolution strategy

https://datatracker.ietf.org/doc/html/rfc8594

https://api-platform.com/docs/core/deprecations/

[arhimede]

https://philsturgeon.com/api-evolution-for-rest-http-apis/

https://datatracker.ietf.org/doc/html/rfc8594

[arhimede]

@alexmerlin
Related to Deprecated attribute
https://wiki.php.net/rfc/deprecated_attribute
https://github.com/JetBrains/phpstorm-attributes

[arhimede]

1. add the Sunset header to the response
2. for the HOME endpoint, add the Deprecated header , for instance say that the metod will be changed from GET to POST on Jan 1, 2025
3. add the new method , POST , for that header
4. this new POST method will still return something extra ?
5. Question : the sunset header, even emtpy, is always present ? check api-platform
6. add to the endpoint list a new column: Deprecated, value the data when is deprecated

[arhimede]

Example:
HEADER
sunset: Wed,01 Jan 2025 00:00:00 +0000
Link: http://example.net/sunset;rel="sunset";type="text/html"

linked resource provides sunset policy information about the service context

[arhimede]

@MarioRadu

the Link item should be

Link: https://docs.dotkernel.org/api-documentation/v5/core-features/versioning;rel="sunset";type="text/html"

[arhimede]

1. in config/autoload/local.php , below the variable $baseUrl, add a GENERIC versioning page URL

example: $versioningUrl = 'https://docs.dotkernel.org/api-documentation/v5/core-features/versioning';

2. IF the variable $versioningUrl is NOT NULL, AND a specific resource is marked as deprecated , send the header

Link: https://docs.dotkernel.org/api-documentation/v5/core-features/versioning;rel="sunset";type="text/html"

3. On a specific endpoint, if there is a specific URL which explains that deprecation , send that specific url in Link header