API lifecycle & deprecation policy

APIs are best thought of as a contract provided by UKG HR Service Delivery to its customers and internal developers. Customers, third-party developers and partners can work with our APIs to build integrations into their own systems. Sometimes it is necessary to phase out an API endpoint (or version). This may be necessary if a field is no longer supported in the result or a business functionality behind an endpoint has to be shut down. There are many other reasons to deprecate an API endpoint.

API lifecycle

In order to provide enough time and visibility, UKG HR Service Delivery applies the following timeline when deprecating an endpoint:

Milestone Name

Milestone Duration (in Months)

Milestone Description

Deprecation

6

When endpoint enters Deprecation period, support and potential patches can still be shipped, but it is tagged with custom headers as detailed in the Deprecation lifecycle: communications and HTTP headers section.

Sunset

6

During the sunset period, no more support or evolution is provided for the resource.

Retired

n/a

Once this milestone reached, the resource is no longer available and returns HTTP responses detailed in the Deprecation lifecycle: communications and HTTP headers section.

Deprecation lifecycle: communications and HTTP headers

Important

API consumers should take action to monitor these new HTTP headers in order to anticpate deprecation of potential useful resources.

In order to warn customers ahead of time, avoid major downtimes and data losses in case of dependencies with the concerned deprecated resources, and regarding the steps described in the API lifecycle section, UKG HR Service Delivery uses the following approach to keep API consumers aware of future deprecations:

  • When entering Deprecation

    • All responses include the following HEADERS:

      • X-Warning-Deprecated: This header returns a timestamp respecting the Date Format Conventions, indicating the effective END DATE of the deprecation period.

      • X-Warning-Deprecated-Notes: In an effort to support migration of API consumers, UKG HR Service Delivery MAY return this header. This header links to online documentation, migration tutorials and/or an API roadmap.

      HTTP/1.1 200 OK
X-Warning-Deprecated: aaaa-mm-qqThh:mi:sszzzzzz
X-Warning-Deprecated-Notes: documentation.people-doc.com/api-release-notes

    • Online API Documentation is updated to reflect this deprecation by tagging the appropriate endpoint/method as Deprecated

  • Once into Sunset period, the following header is included in all responses:

    • Sunset: this is a timestamp header (see specification) indicating the effective END DATE of the Sunset period. Once this header is returned, no more support is provided by the UKG HR Service Delivery Team.

  • Lastly, once Retired, the endpoint:

    • Doesn’t return payload previously documented.

    • If there is a new version of the endpoint/method, the following headers are ALWAYS returned: - 301 MOVED PERMANENTLY - Location to allow discovery of the new version of the endpoint/method.

    • If there is no new endpoint/method, http status code returned is - 410 GONE