API Deprecation Strategy

APIs are best thought of as a contract provided by UKG to its customers and internal developers. Customers or third-party developers and partners can work with our APIs to build integrations on their own systems. Sometimes it is necessary to phase out an API endpoint (or version). For example, 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 could be other reasons as well.

Sunset Period

Sunset period provides our API consumers with an adequate time to upgrade to a newer version or retire the functionality before the API stops working. In order to provide a smooth transition for our customers and internal developers, UKG defines sunset period as a combination of 6 months of fully functional and supported API and another 6 months of functional API with no additional support.

Proper API Versioning

Proper API versioning helps to deprecate API reliably and effectively. Multiple versions of the same functional API can live simultaneously. Release of the next API version may permit deprecation of a previous version. E.g. release of API v2 may permit deprecation of API v1 by beginning the sunset period for API v1. New API version does not necessarily mean deprecating the previous version - sometimes it is desired to keep both versions for compatibility or contractual obligations.

Communication to our API Consumers

Communication to the API consumers, customers and internal developers, is an important part of API deprecation phase. For this reason, we send an initial message announcing the intended deprecation, with the proposed deprecation "sunset", next version release schedule (if applicable), and additional information such as support, contact information, etc.

Reflect Deprecation in the API Definition

API deprecation is part of the OpenAPI definition. If a method on a path or a whole API endpoint should be deprecated, UKG will set deprecated=true on each method/path element that will be deprecated. If deprecation needs to happen on a more granular level (i.e. query parameter, payload etc.), UKG will set deprecated=true on the affected method/path element and add further explanation to the description section. If deprecated is set to true, UKG will describe what our clients should use instead and when the API will be shut down in the description section of the API definition. UKG's API documentation will reflect the deprecated API:

Adding a Warning Header to Responses

During deprecation phase, UKG will add a Warning header (see RFC-7234) to the API response: Warning: 299 “https://ulticonnect.ultimatesoftware.com/personnel/v1/employees” “The API is deprecated and will be removed on [Sat, 25 Aug 2012 00:00:00 GMT]”, where date is in HTTP-date format defined by RFC-2616. The square brackets are intended to help our customers with date parsing automation. Consumers will be able to read Warnings, automatically detect, and include this information into logs for human attention.

Monitoring for Warning Header

It is important for all of our API consumers to monitor Warning headers in HTTP responses to see if an API will be deprecated in the future. Warnings headers written into logs by the HTTP Clients help developers to detect API forthcoming deprecation and migrate to newer version in a timely fashion.

Helping Our Customers to Avoid Problems

As an API provider, we help our consumers avoid possible errors within their products due to API deprecation. After an API is deprecated, these are few simple steps that UKG takes that will help our API consumers:

• If the endpoint functionality is completely removed, we will respond with 409 "Gone" status instead of 404 "Not Found". This allows our consumers to have different error handling which avoids confusion with incorrectly implemented or missing API.
• If the endpoint functionality was replaced with a newer implementation, we will respond with 301 "Moved Permanently" status providing a newer endpoint URL. This allows our consumers to call an alternative API as a fallback fault tolerant strategy.
• UKG will keep documentation for deprecated endpoints for a prolonged period of time, replacing its content with reference to the newer implementation, or (if it was removed completely) provide a note indicating this.