Introduction to the structure of the ADP REST APIs

Summary: ADP APIs are designed using an event based pattern for resource management. This pattern separates the act of retrieving resources and modifying them into separate activities along with providing event notifications that indicate the changes to a resource.

Retrieving Resources

The most common method to retrieve resources via the ADP REST APIs is to do a GET against the resource endpoint. By default this request will return all resources of the given type but supports several query parameters to control what is returned.

Say the resource you are interested is Worker v2. The request to get all workers is

GET

https://api.adp.com/hr/v2/workers

You can control the results returned by using the following query parameters:

  • $top : specifies the upper limit on the number of items to return
  • $skip : specifies the number of items to skip from the begining of the list
  • $orderby : specifies an expression that is used to order the items to be returned
  • $select : specifies the properties of the items to include in the response
  • $filter : specifies an expression that an item must match to be included in a response

For example one can:

Request only the first 10 workers:

GET

https://api.adp.com/hr/v2/workers?$top=10

Request that the workers be returned sorted by last name:

GET

https://api.adp.com/hr/v2/workers?$orderby=/person/legalName/familyName1

Modifying Resources

ADP REST APIs use an event based pattern for resource modification. The events (i.e. requests for modification) are POSTed to ADP and each event specifies the target of the change and the modification requested. The response to the request lets you know if the requested changed was made or rejected.

For example a Worker v2 (also used in the example above) can contain a list of personal email addresses. There are three events defined that enable making changes to a worker’s person email address list. These events are:

  • Add Worker Personal Email v1
  • Change Worker Personal Email v1
  • Remove Worker Personal Email v1

Lets add a new email address to a worker. The following post is adding the email address mynewemail@gmail.com to the user with the associate OID specified in the event context of the event.

POST

https://api.adp.com/events/hr/v1/worker.personal-communication.email.add

{
  "events" : [ {
    "serviceCategoryCode" : {
      "codeValue" : "hr"
    },
    "eventNameCode" : {
      "codeValue" : "worker.personalCommunication.email.add"
    },
    "originator" : {
      "associateOID" : "G557KMGC6KCSVZRD"
    },
    "actor" : {
      "associateOID" : "G557KMGC6KCSVZRD"
    },
    "data" : {
      "eventContext" : {
        "worker" : {
          "associateOID" : "G3GMA28TB2SVJ2TF"
        }
      },
      "transform" : {
        "eventStatusCode" : {
          "codeValue" : "submit"
        },
        "worker" : {
          "person" : {
            "communication" : {
              "email" : {
                "emailUri" : "mynewemail@gmail.com"
              }
            }
          }
        }
      }
    }
  } ]
}

In this case the response shows that the email was successfully added. This is indicated by a 201 HTTP response code along with the eventStatusCode and the content in the output section of the event:

{
  "events" : [
    {
      "eventStatusCode" : {
        "codeValue" : "complete",
        "shortName" : "complete"
      },
      "data" : {
        "eventContext" : {
          "worker" : {
            "associateOID" : "G39YC8VQ618GBFP9"
          }
        },
        "output" : {
          "worker" : {
            "person" : {
              "communication" : {
                "email" : {
                  "emailUri" : "mynewemail@gmail.com"
                }
              }
            }
          }
        }
      }
    }
  ]
}

Event Notifications

Applications can receive notifications of changes. All the notifications that are subscribed to are received at a single API endpoint. This endpoint is:

GET

https://api.adp.com/core/v1/event-notification-message