Rest Requests
The Humanity API allows you to call modules with the Humanity service that respond in REST style json or xml.
The API URL is located at https://www.humanity.com/api/
Although we support multiple output types, all requests to the Humanity API are packaged as string representation of the JSON request object and sent only in the POST HTTP Request Method. Virtually all requests require an authentication token. The following parameters are accepted on each call:
- key :Required for initial authentication
- token : Authentication token where required
- request : JSON object carrying all parameters for your request
- output : json, xml, simplexml, html (default=json)
Example data:
{
"key": "xxxxxxx",
"token": "xxxxxxx",
"output": "json",
"request": [
"see below"
]
}
Remember that any data passed to the API is to be formatted as JSON, and its string value needs to be sent via the POST HTTP request method all as the post variable 'data' (Checkout the 9th line from an example below). Also Content-Type needs to be set to application/x-www-form-urlencoded. Here is an example of what this looks like in PHP:
CALL VARIABLES
$api['key'] = 'xxxxxxx';
$api['output'] = 'html';
$api['request'] = array('username'=>'ryan', 'password'=>'nicetry');
OPEN CURL CONNECTION
$ch = curl_init();
curl_setopt($ch,CURLOPT_URL, 'https://www.humanity.com/api/');
curl_setopt($ch,CURLOPT_POSTFIELDS, <b>'data='.json_encode($api)</b>);
EXECUTE COMMAND
$result = curl_exec($ch);
CLOSE CONNECTION
curl_close($ch);
REQUEST
This object contains all of the variables that will be used to handle your request - including the api module, method as well as any method particular parameters.
- module : API module (default=staff.login)
- method : GET, CREATE, UPDATE, DELETE (default=GET)
- ... : Any module specific variables
Example request:
{
"module": "staff.login",
"method": "GET",
"username": "[email protected]",
"password": "nicetry"
}
ACCEPTED VARIABLE TYPES
The Humanity API is strict with what variables it accepts in the request field. Meaning that you MUST pass the required variables for that module(if any), and you can ONLY pass other variables with are accepted by that module (if any).
For every variable that is passed we are also strict on the variable type that is allowed:
- integer : Integer Values only
- varchar : Variable Characters(default)
- enum : only values from this list
- min length : Minimum variable length
- date : Valid Humanity Date ID, Unix TimeStamp or any date accepted by strtotime
- time : Valid Humanity Time ID, any time accepted by strtotime
- email : Valid E-mail
- phone : Valid Phone Number
REST RESPONSES
Regardless on what output type you select the API will return data in the following format every time:
- status : Response code of request (success=1)
- data : Data returned in your request
- token : Authentication Token (if authenticated)
EXAMPLE RESPONSE: (JSON)
{
"status": "1",
"data": [
{
"name": "Ryan Fyfe",
"email": "[email protected]"
},
{
"name": "Mark Ryder",
"email": "[email protected]"
}
],
"token": "xxxxxxx"
}
EXAMPLE RESPONSE: (XML)
<?xml version="1.0"?>
<response>
<status>1</status>
<data>
<item>
<name>Ryan Fyfe</name>
<email>[email protected]</email>
</item>
<item>
<name>Mark Ryder</name>
<email>[email protected]</email>
</item>
</data>
<token>xxxxxxx</token>
</response>
EXAMPLE RESPONSE: (SIMPLEXML)
<?xml version="1.0"?>
<response>
<status>1</status>
<data>
<name>Ryan Fyfe</name>
<email>[email protected]</email>
</data>
<data>
<name>Mark Ryder</name>
<email>[email protected]</email>
</data>
<token>xxxxxxx</token>
</response>
EXAMPLE RESPONSE: (HTML)
status 1
data
0
name Ryan Fyfe
email [email protected]
1
name Mark Ryder
email [email protected]
token xxxxxxx
ERROR RESPONSE: (JSON)
In the event of an error we provide the error number, and error description(in the data field), as well as an extra variable called 'error' which can be used for more detailed debugging or error reporting. eg:
{
"status": "9",
"data": "Invalid parameters - Your request has an invalid parameter type",
"error": "date expected: start_date",
"token": ""
}
You'll notice in the above that we both receive a response using the standard error codes, as well as in the 'error' field we have more detailed information that points us directly to the field that is wrong.
MULTIPLE REQUESTS/RESPONSES
You can very easily make multiple requests to our API (up to 5 at a time). This will allow you to collect data from the API much faster, and make much more responsive applications. The format for request/response, is basically identical to when making individual requests except for now both the input/output are arrays as well.
EXAMPLE REQUESTS: (JSON)
{
"key": "xxxxxxx",
"token": "xxxxxxx",
"output": "json",
"request": [
{
"module": "schedule.shifts"
},
{
"module": "staff.employees"
},
{
"module": "staff.employees"
}
]
}
In this same way you can make requests of different types(GET,DELETE,UPDATE,CREATE) with a single call to the API:
[
{
"status": "1",
"data": [
{
"name": "Ryan Fyfe",
"email": "[email protected]"
},
{
"name": "Mark Ryder",
"email": "[email protected]"
}
],
"token": "xxxxxxx"
},
{
"status": "1",
"data": [
{
"name": "Ryan Fyfe",
"email": "[email protected]"
},
{
"name": "Mark Ryder",
"email": "[email protected]"
}
],
"token": "xxxxxxx"
}
]
<?xml version="1.0"?>
<response>
<item>
<status>1</status>
<data>
<item>
<name>Ryan Fyfe</name>
<email>[email protected]</email>
</item>
<item>
<name>Mark Ryder</name>
<email>[email protected]</email>
</item>
</data>
<token>xxxxxxx</token>
</item>
<item>
<status>1</status>
<data>
<item>
<name>Ryan Fyfe</name>
<email>[email protected]</email>
</item>
<item>
<name>Mark Ryder</name>
<email>[email protected]</email>
</item>
</data>
<token>xxxxxxx</token>
</item>
</response>
Updated about 6 years ago