Developer Center

Our API infrastructure utilizes consistent terminology and labeling

Hypermedia Controls

The Paychex APIs are based on Hypertext as the Engine of Application State (HATEOAS). Hypermedia-style APIs differ from RPC-style approaches in that the message design contains more than just data. The message also includes control information that represents the operations that can be performed on the resource being presented.

With hypermedia controls a document is used to capture the "states", "transitions", and "data elements" associated with the problem domain. The problem domain is also documented from the perspective of the client using a task-oriented approach. Tasks are captured as state transitions which are expressed as links and forms. All transitions have the same basic features. They indicate a URL for the transition target and have one or more variables to hold values to send to the server when activating the transition.

It is important to note that our Hypermedia APIs are focused on representing the state of the application rather than the objects or functions that affect that state. The problem domains of our APIs are separated by Products. Common domains include Payroll, Time & Labor, Human Resources (HR). Within a problem domain, states are represented as named resources. State transitions are captured as HATEOAS links. Data elements are used to to convey the current state and can be returned in responses or used as parameters in making transition requests. When using hypermedia links, the actions you can perform are captures as the " rel " and the URL you need to used in order to transition into the next state associated with the action is captured as the " href ". Paychex recommends that developers focus on using the actions to perform the tasks they need to accomplish and use the link information associated with those actions to provide the detail.

Each call that you make to an API will return a document. Within that document we will return the data elements associated with the current state along with an array of links that present the states transitions you can call. The "links" arrays will be a top level field in your document and looks like:

{
  "links" : [
    {
      "href" : "https://api.paychex.com/companies/99Z5V9BTI8J2FCGESC05/workers?offset=5&limit=5",
      "rel" : "self"
    },
    {
      "href" : "https://api.paychex.com/companies/99Z5V9BTI8J2FCGESC05/workers?offset=10&limit=5",
      "rel" : "next"
    },
    {
      "href" : "https://api.paychex.com/companies/99Z5V9BTI8J2FCGESC05/workers?offset=0&limit=5",
      "rel" : "prev"
    }
  ]
}

There are two components for each link in a HATEOAS links array:

Link NameDescription
hrefThe URL (resource) to use to transition to the next state
relThe link relation that describes the state transition