Person API: Perspective on Versioning With the Transition to Workday

As part of the transition from Peoplesoft to Workday, the Person API will also be changing to source its HR data from Workday. The Person API has been designed to abstract the underlying systems it gets data from, and instead express data in a way that is generic but meaningful to UW integrators. This makes a shift in underlying systems less impactful on integrations. Most of the changes can be made in the connection between the API and the underlying system, eliminating changes needed by integrations that use the API.

We in the DoIT Enterprise Integration API Team have been continually adding to the API without creating new versions. On the Developer Portal, we document the specific expectations of integrators that use the Person API to show how changes are made to preserve backwards compatibility. See “Versioning and breaking changes” and “Accommodate new attributes” on this page for more information.

However, with the transition to Workday, large changes may require a new version of the Person API, regardless of how much abstraction we are able to do. The transition from UDDS to the new organizational data structures in Workday is an example of something that may require a new version of the Person API, rather than adding to the existing version within the bounds we document for integrators.

It is too early to conclude whether a new version of the Person API will be required with the transition to Workday, but whether it is required or not, here are our principals for how we intend to handle this transition:

  • If we can avoid creating a new version of the Person API, we will do so, since this will reduce the amount of work that is needed by UW integrators who use the Person API.
  • We will avoid abstracting changes to the extent that they would go “against the grain” of how the data is expressed and understood in other means of integrating and consuming data. For example, if there was a way to abstract the change of transitioning from UDDS, and therefore eliminate the need for integrations to move to new organizational data structures, we would not pursue this route since UDDS is being deprecated in all other contexts at UW.

If a new version of the Person API is required to transition to Workday, here’s how we would likely accomplish this:

  • Create a new version of the Person API with the changes that would otherwise break the existing version. This new version would be used by changing the HTTP request to the API, for example, by using a different URL or header to indicate the new version. The new version would be created before the Workday go-live.
  • Deprecate the existing version of the Person API and set a date to disable the existing version. This date would likely be aligned with the go-live date of Workday. Deprecating the existing version means that we would discontinue requests for new integrations to access it and discontinue adding new data or features to it. All new requests to access the Person API would be based on the new version.
  • To the extent possible, have the new version of the Person API use current, real, and usable data, from the beginning, such that UW integrators could start using the new version immediately. This would lessen the burden of transitioning to the new version, since less coordination would be required. The longer overlap in availability with the old and new versions, the better.
  • Our API Management platform would help with targeted communication and monitoring usage of the old and new versions.

If a new version of the Person API is not required to transition to Workday, here’s our idea for how this would be handled:

  • Any upcoming changes to the Person API (e.g. new attributes, changing values for existing attributes) would be communicated as early as possible to API consumers. This information would also be available in greater depth in blog posts on Integrate Data, which would include example “before and after” data payloads and planned/future OpenAPI specifications.
  • Any values changing for existing attributes would have an associated date of when those values would be changing (e.g. the value for a job’s position, which will be changing when transitioning to Workday).
  • When changes are made to the API, they would be reflected in the documentation in the Developer Portal, including the Person API release notes.

Based on our versioning principals described above, our default is to not create a new version of the Person API unless absolutely required. As we become aware of requirements that lead us down a path of versioning, we will communicate this to existing Person API users and in sprint reviews. All the changes described above apply to the Mock Person API too. For example, a new version of the Person API would also mean a new version of the Mock Person API.

Feel free to email our team (api@doit.wisc.edu) with any questions or feedback on our API versioning perspective. Anyone at UW is welcome to attend our bi-weekly sprint reviews, so let us know if you’d like to be invited.

Jared Kosanovic – Enteprise Integration Architect

Division of Information Technology