Conventions

Response Format

At a high level, there are two possible response formats you will encounter. One for success conditions and one for failure conditions. Within those paths, parameters may vary depending on the verb used and the status range returned.

HTTP Status

The HTTP Status header is always used to indicate success or failure at a high level. Statuses are used appropriately and consistently:

• 200 range indicates success.
• 400 range indicates errors fixable by the API consumer: authentication, bad formatting, data validation issues, etc.
• 500 range indicates errors on our end: server issues, maintenance downtime, etc.

Success

{
	"status": 200,
	"code": 2000
}

In a successful response, you will always receive a status in the 200 range. This is a duplicate of the HTTP status code. You will also receive a code in the 2000 range. This is a Zengine specific code that can be used for more context.

GET, POST and PUT

{
	"status": 200,
	"code": 2000,
	"totalCount": 2,
	"limit": 20,
	"offset": 0,
	"data": [
		{
			"id": 1,
			"attributeOne": "some value"
		},
		{
			"id": 2,
			"attributeOne": "some other value"
		}
	]
}

A totalCount, limit, and offset is provided for all GET, POST and PUT requests.

data holds information about the object(s) being fetched, created or modified. data is an array, as shown above, when representing lists of objects. In single-object scenarios, data itself becomes the object. For example:

{
	"status": 200,
	"code": 2000,
	"totalCount": 2,
	"limit": 20,
	"offset": 0,
	"data": {
		"id": 1,
		"attributeOne": "some value"
	}
}

Failure

{
	"status": 404,
	"code": 4004,
	"userMessage": "Error viewing data",
	"developerMessage": "No data was found"
}

In a failure response, you will always receive a status in the 400 or 500 range. This is a duplicate of the HTTP status code. You will also receive a Zengine specific code in the 4000 range. This code can be used for better context.

The userMessage is a string containing friendly text that you can pass directly on to an end user. The developerMessage is geared towards the developer.

POST and PUT: User Error

{
	"status": 403,
	"code": 4012,
	"userMessage": "Error saving data",
	"developerMessage": "Validation errors",
	"validationErrors": {
		"attributeOne": [
			"Some error message"
		],
		"attributeTwo": [
			"Some error message",
			"Some other error message"
		]
	}
}

When invalid data has been POSTed or PUT, validationErrors will also be returned. These errors will be returned in the same keyed format they were provided tot he API, which means they can be programmatically passed back to an end user with ease. Note that each attribute contains an array with one or more errors that are associated with that attribute.