Workday Web Services Versioning

Versioning within our Workday Web Service is essential to achieving our vision behind loosely-coupled, non-brittle integrations. Web service versioning allows for your Workday-based integrations to remain stable and fully functional as our Workday Business Services continue to evolve and mature. Our approach to web service versioning leverages both a "version parameter" and a "version endpoint" design pattern. Our "version parameter" design pattern including a version number in the request as a parameter that determines how the request is processed within Workday and what kind of response to return. Our "version endpoint" design pattern is very similar to our "version parameter" pattern but instead of putting the version into the request, it becomes part of the URL endpoint that is being invoked. The versioning of our Workday Web Services help to ensure that you get the most out of your Workday integration investments.

Deprecation Policy and Supported Versions

All announcements surrounding the availability of new web service versions will be communicated through our "What's New in Workday" notes and also in the Workday Web Services Release Notes. Please refer to our WWS API Support Policy for additional information on supported versions and deprecation policies.

New Versions of Workday Web Services

In general, new versions of Workday Web Services will only be introduced when changes to our existing interfaces are not backwards-compatible with the current version. In other words, the current version will evolve and change over time as long as updates are non-destructive and fully backward compatible. This policy is in place in order to provide a superior level of customer support within our Workday Web Services. With this policy, new operations, non-required elements, and attributes can be added to our Workday Web Services to facilitate customer requests for integrations and go-live dates. The types of changes that are backwards-compatible are:

  • Addition of new WSDL operations to an existing WSDL document.
  • Addition of new XML schema types within a WSDL document that are not contained within previously existing types.
  • The types of changes that are not backwards-compatible are:
  • Removing an operation
  • Renaming an operation
  • Changing the parameters (in data type or order) of an operation
  • Changing the structure of a complex data type.

Using Versions in Workday Web Services

When leveraging our Workday Web Services, you can reference version information within your integration development with:

Endpoint Versioning

Endpoint Versioning allows you to specify the version to use for your integration development within the endpoint. The format for the endpoint is:

Endpoint Versioning - Service endpoint with version information:

https://{your Workday domain}/ccx/service/{your tenant name}/{desired Workday Service}/{desired Workday Service Version}
ex. https://services1.workday.com/ccx/service/acme/Human_Resources/v1

Endpoint Versioning - WSDL endpoint with version information:

https://{your Workday domain}/ccx/service/{your tenant name}/{desired Workday Service}/{desired Workday Service Version}?wsdl
ex. https://services1.workday.com/ccx/service/acme/Human_Resources/v1?wsdl

Message Versioning

Message Versioning allows you to specify the version to use for your integration development within the SOAP-based message itself. The format / schema for the message is:

Message Versioning - SOAP-based XML message with version information:

<soapenv:Envelope xmlns:bsvc="urn:com.workday/bsvc" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <bsvc:Business_Site_Find bsvc:version="v1">
      <bsvc:Business_Site_Name>This is an Example</bsvc:Business_Site_Name>
    </bsvc:Business_Site_Find>
  </soapenv:Body>
</soapenv:Envelope>

Message Versioning - SOAP-based XML root element schema snippet with version information:

<xsd:attribute name="version" type="xsd:string" wd:fixed="v1" />
<xsd:complexType name="Business_Site_FindType">
  <xsd:sequence>
    <xsd:element maxOccurs="1" minOccurs="0" name="Business_Site_Name type="xsd:string" />
  </xsd:sequence>
  <xsd:attribute ref="wd:version" use="required" />
</xsd:complexType>
*NOTE: If version information is included in both the message and the endpoint, the message version is used.