Conventions

General

Base Path

The Version 1 REST API base path is:

https://api.stage.zenginehq.com/v1

HTTPS Required

For security reasons, the API is only open on HTTPS (Port 443). All other traffic will be blackholed.

Timestamp Format

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

2013-05-01T14:00:00Z

Default Timezone

Media Type Support

POST and PUT data can be received in the following formats:

• application/json
• application/xml
• application/x-www-form-urlencoded
• multipart/form-data (required and only applicable on requests including file uploads)

You must specify your preference using the Content-Type header. For example:

Content-Type: application/json

Media can be returned in JSON, XML and CSV formats:

• application/json
• application/xml
• text/csv

You can specify your preference as a URL extension or by using the Accept header. The URL extension takes precedence. For example:

https://api.stage.zenginehq.com/v1/{resource}.json
Accept: application/xml

... will return a JSON-formatted response

JSONP

A ?callback parameter can be used with any GET request to have the results wrapped in a JavaScript function. This is typically required for client-side applications which needs to make cross-domain requests to the Zengine API without using a proxy or the more modern Cross-Origin Resource Sharing (CORS) strategy.

Example:

https://api.stage.zenginehq.com/v1/{resource}.json?callback=foo

foo({
	"status": 200,
	"code": 2000,
	// etc
});

The JavaScript to handle the callback might look something like this:

function foo(response){
	console.log('Status: ' + response.status);
}

JSON Pretty Printing

Typically, a JSON response will be served without any whitespace, saving bandwidth. For example:

https://api.stage.zenginehq.com/v1/{resource}.json

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

It is often helpful to make this more readable for the purposes of API discovery and debugging. You may use the ?pretty=1 parameter to return data in "pretty print" format:

https://api.stage.zenginehq.com/v1/{resource}.json

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