Working with the API

This guide is aimed at familiarising you with some of the key components in this API. It is recommended that you familiarise yourself with our Object Hierarchy as however familiar you are with payroll some of these concepts may differ from system to system.

The API provides a RESTful solution to managing the payroll entities. Using HTTP requests, it is possible to insert, update, en-queue and delete the payroll data.

Headers Used for:

  • Authorisation: used to supply the OAuth credentials
  • API-Version: sets the API version to be targeted management
  • Content-type: specifices the data type transmitted to the server (JSON or XML format).
  • Accept: specifices the data type required in the response from the server (JSON or XML format).

URI Used for:

  • Single Resource: targets a single resource instance
  • Link Collection: targets a collection of resource links

Verb/Method Used for:

  • [GET] retrieves resources
  • [PUT] inserts or updates resources
  • [POST] inserts a new resource into a parent collection
  • [PATCH] sparse update to a resource (i.e. only update a single property)
  • [DELETE] remove the resource (this is a hard delete and cannot be undone!)

Request Body Used for:

  • PUT inserts or replaces the targeted entity
  • POST inserts a new entity in the targeted entity collection.
  • PATCH updates an existing entity with the specified values.

Response Body Used for:

  • The result of the query or action performed.

URI flavors

The relationship between payroll entities is controlled by URIs. The unique resource identifiers follow two distinct patterns that indicate entities and associated child collections of entities.

By design, the API does not return the complete representation when getting collections. Instead, a list of entity links are returned. Entity links include a brief description of the entity and the URI location where the entity object resides.

Single Entity Location

This pattern of URI points to a single entity. Consisting of a entity type and unique key pair. The entity type and unique key pairs are chained together to represent the data structure hierarchy. Child entities are selected by extending the URI to include the child element specification.

Example This example URI points to an employee with a unique key of "EE001" that exists under an employer with a unique key of "ER001".

Http methods:

  • GET - Retrieves the employee information
  • PUT - Inserts or updates the employee
  • DELETE - Removes the empoyee
  • PATCH - Merges the supplied data with the existing resource
  • POST - Not supported for explicit URIs

Entity Collection Location

The collection location URI determines the parent container for the specified action. They follow a pattern of indicating a parent entity followed by the pluralised name of the data type.

Example This example of a collection location URI points to the collection of Pay Instructions associated to an employee with unique key "EE001" under an employer with unique key "ER001".

Http methods:

  • GET - Retrieves a collection of pay instruction links
  • PUT - Not supported for collection locations
  • DELETE - Not supported for collection locations
  • PATCH - Not supported for collection locations
  • POST - Inserts a new instruciton into the target collection with an auto generated unique key