Provide additional information about GoCD deprecated APIs

[GaneshSPatil]

Issue Type

• Feature proposal

Summary

There is no way for the clients consuming GoCD APIs to know whether the API under use is deprecated or not.

Add following additional information for the deprecated GoCD APIs

• Deprecation Header
  Whether the API is deprecated or not (along with the time when api was deprecated)
• Sunset Header
  When the API will be removed.
• Link
  Possibly add the link to the newer API version?
• Warning
  Add a warning about the deprecated API

[GaneshSPatil]

@gocd/committers - Thoughts?

[GaneshSPatil]

Example

Config Repo API v2 will be deprecated in GoCD Release v20.2.0 and removed in GoCD Release v20.5.0 (June Release)

X-GoCD-API-Deprecated-In: v20.2.0
X-GoCD-API-Removal-In: v20.5.0
X-GoCD-API-Deprecation-Info: https://api.gocd.org/20.2.0/#api-changelog
Link: https://ci.example.com/go/api/admin/config_repos/repo1; Accept="application/vnd.go.cd.v3+json"; rel="successor-version"
Warning: 299 GoCD/v20.2.0 "The Config Repos API version 2 has been deprecated in GoCD v20.2.0. This version will be removed in a release scheduled for May 2020. Version 3 of the API is available, and users are encouraged to use it."

Description:

As GoCD is a self-hosted tool, specifying Date values for deprecation header would be tough and confusing, because:

• Specifying removal date (future) would require GoCD to make release(s) on particular date(s).
• If the end users of GoCD decide not to upgrade and use a particular version of GoCD, lets say v20.1.0, even when the removal date has elapsed, the API will continue to work.

As the GoCD API deprecations are tied to GoCD versions and not to dates, use GoCD release version in the API deprecation headers.

Header Description:

• X-GoCD-API-Deprecated-In:
  This Response header denotes the GoCD Version when the API was deprecated.

• X-GoCD-API-Removal-In:
  This Response header denotes the GoCD Version when the API will be removed.

• X-GoCD-API-Deprecation-Info:
  This Response header provides a link to the GoCD API deprecation documentation.

• Link:
  This Response header has following 3 parts:

  • Link: The successor API link.
  • Accept Header: The successor API's version Accept Header. Know more about it here.
  • rel: Denoting the relation of the link with the API. This field has a fixed value successor-version denoting the specified link and the accept header is the successor of the current API.

• Warning:
  This Response header has following 3 parts:

  • Warning Code: The warning code. This field has a fixed value 299. Know more about warn-code at MDN.
  • Warning Agent: The agent adding this warning. This field represents the GoCD version adding the warning in the format GoCD/<GoCD_Vesion>
  • Warning Message: The warn message.

Resources:

• https://tools.ietf.org/id/draft-dalal-deprecation-header-01.html#implementation-status
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Warning
• https://zapier.com/engineering/api-geriatrics/

[GaneshSPatil]

Deprecate following GoCD APIs

Release 20.2.0

API	Deprecated Version	Successor Version	Deprecated In	Removal In
Template Config	v6	v7	20.2.0	20.5.0
Config Repos	v2	v3	20.2.0	20.5.0

Release 20.1.0

API	Deprecated Version	Successor Version	Deprecated In	Removal In
Notification Filter	v1	v2	20.1.0	20.4.0
Feeds API	v1	v2	20.1.0	20.4.0
Pipeline Instance API	unversioned	v1	20.1.0	20.4.0
Pipeline Status API	unversioned	v1	20.1.0	20.4.0
Job History API	unversioned	v1	20.1.0	20.4.0
Stages API	v1	v2	20.1.0	20.4.0

Release 19.12.0

API	Deprecated Version	Successor Version	Deprecated In	Removal In
Template Config	v5	v6	19.12.0	20.3.0
Pipeline Group Config Listing	unversioned	null	19.12.0	20.3.0
Agent Job Run History	unversioned	v1	19.12.0	20.3.0

[dret]

this all looks reasonable, if all you want to communicate are versions. i'd like to suggest that adding timestamp information may be useful because that would tell people when to expect deprecation and sunsetting. in the end, what consumers need to know is how long they can expect the API to be current, and to work at all.
maybe support Sunset because it's an RFC, and support Deprecation as well (we're working on getting this through the approval process right now), so that you expose the timestamp information in a standards-based way. you can still use the version-based header fields if that is still information that you want to expose in your API.
thanks for your consideration, and kind regards!

[GaneshSPatil]

Hi @dret,

Thank you very much for the suggestion. We did consider adding a timestamps to the deprecations and sunsetting, but it has following complications:

1. GoCD is available as a package distribution and not a hosted solution. So, we do not really have control over the timestamps. Meaning, if an API is deprecated in April release and is suppose to be removed in July. We need to know the GoCD April and July release dates. And then we'll be forced to make a release a specific dates as the April release would've hard-coded the API removal date of July.

Note: This point is true assuming users upgrade immediately as the new release is available.

2. Let's assume as part of GoCD v20.2.0 an API X was deprecated in Feb and the removal date is in April. GoCD makes a release in April v20.4.0 which removes API X.
   But if the user doesn't upgrade to GoCD v20.4.0 and continues with GoCD v20.2.0, the API X will continue to work even post the removal date.

Hence, for GoCD, the API deprecations and removal are based on the GoCD release versions and not dates.