Employgroup API

As a REST-based service, the Employgroup API supports the standard HTTP status codes. This document provides more information on the status codes that you should expect to see during normal operations.

The Employgroup API supports the following HTTP Status Codes. If you are unsure of the terms used here, please refer to the W3C documentation.

Successful 2xx

This class of status codes indicates that the API request was successfully received, understood, and accepted.

200 OK

The request has succeeded, and the requested resource or resources will be returned in the response body in the requested format.

If a GET API endpoint returns a resource collections and exposes pageNumber and pageSize parameters, then the results of the query will be paginated. In that case, the Links response header will contain a number of references to other pages of data, which can then be used to easily navigate through the resultset. Additionally, there will be several custom headers to provide more metadata about the resultset:

X-Paging-PageNumber - the current page number in the resultset;
X-Paging-PageSize - the number of resources to return per page;
X-Paging-TotalPages - the total number of pages in the resultset;
X-Paging-TotalRecords - the total number of resources in the resultset;

A sample request paginated request looks like this:

> curl -X GET https://api.epayroll.com.au/ExpenseApplications?pageNumber=3&pageSize=20

HTTP/1.1 200 OK
Content-Length: 7092
Content-Type: application/json; charset=utf-8
Link: </ExpenseApplications?pageNumber=3&pageSize=20>;rel="self",
</ExpenseApplications?pageNumber=1&pageSize=20>;rel="first",
</ExpenseApplications?pageNumber=2&pageSize=20>;rel="prev",
</ExpenseApplications?pageNumber=4&pageSize=20>;rel="next",
</ExpenseApplications?pageNumber=5&pageSize=20>;rel="last",
X-Paging-PageNumber: 3
X-Paging-PageSize: 20
X-Paging-TotalPages: 5
X-Paging-TotalRecords: 96
[
// ...
]

We are in the process of migrating all API endpoints that return resource collections to return paginated results.

201 Created

The request has been fulfilled and resulted in new resource being created. The newly-created resource can be referenced by the URI returned in the Location header field.

> curl -X POST https://api.epayroll.com.au/v11.5/ExpenseApplications \
  -H 'content-type: application/json' \
  -d '{
	"AmountApplied": 109.25
}'

HTTP/1.1 201 Created
Content-Length: 0
Location: /ExpenseApplications/123456

A 201 response may contain an ETag response header field indicating the current value of the entity tag for the requested resource just created.

202 Accepted

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.

The entity returned with this response will include an indication of the request's current status and a pointer to a status monitor.

204 No Content

The server has fulfilled the request but does not need to return an entity body.

This typically occurs in response to a PUT or DELETE request.

> curl -X DELETE https://api.epayroll.com.au/v11.5/ExpenseApplications/123456

HTTP/1.1 204 No Content
Content-Length: 0

All DELETE operations in the Employgroup API are idempotent - in other words, successive calls to the same resource will return the same result each time. So if you try to delete a resource that has already been deleted, you will get a 204 No Content rather than a 404 Not Found.

Redirection 3xx

This class of status codes indicates that further action needs to be taken by the user agent in order to fulfil the request.

301 Redirect: The requested resource no longer exists at the specified URI, but has been moved to another location.

304 Not Modified: Where an ETag has been issued for a resource retrieved by a GET request, if that ETag is included in a GET request and the resource has not been modified, then the server will respond with this status code. The response will not contain a body.

Client Error 4xx

This class of status code is intended for cases in which the client seems to have erred. The server should provide some explanation of the error situation, and an indication of whether this is a permanent or temporary condition.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

This will usually occur when the resource fails business logic tests, validation rules etc.

> curl -X POST https://apiuat.aussiepay.com.au/v11.5/ExpenseApplications \
  -H 'content-type: application/json' \
  -d '{
	"AmountApplied": 109.25
}'

HTTP/1.1 400 Bad Request
Content-Length: 704
{
    "Message": "The request is invalid.",
    "ModelState": {
        "command.OrganisationChartPositionId": [
            "The field OrganisationChartPositionId is a required field."
        ],
        "command.ExpensePaycodeId": [
            "The field ExpensePaycodeId is a required field."
        ],
        "command.EmployeeId": [
            "The field EmployeeId is a required field."
        ]
    }
}

401 Unauthorized

The request requires user authentication. The response will include a WWW-Authenticate header field containing a challenge applicable to the requested resource. The client may repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorisation has been refused for those credentials.

403 Forbidden

The server understood the request, but is refusing to fulfil it. Authorisation will not help and the request should not be repeated.

404 Not Found

The server has not found anything matching the request URI. No indication is given of whether the condition is temporary or permanent.

This status code can either mean that the resource endpoint, such as /ResourceThatDoesNotExist, does not exist, or that a specific resource on a valid resource endpoint does not exist, such as /Employees/1234567.

Server Error 5xx

Response status codes beginning with the digit 5 indicate cases in which the server is aware that it has erred or is incapable of performing the request.

500 Internal Server Error: The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable: The server is currently unable to handle the request due to a temporary overloading, or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay may be indicated in a Retry-After header.

HTTP Codes

Successful 2xx

Redirection 3xx

Client Error 4xx

Server Error 5xx