API Data Types and Notes
The following guide applies to our API at runtime and data exchange.
API Success Messages
All successful calls to the FS API will return HTTP status code 200 OK or status code 202 Accepted. You will receive a HTTP 202 when the request you are making has already been previously made, or is identical to a previous request.
API Failure Messages
Error conditions return HTTP 4xx error codes.
Error codes can also include authentication and permissions errors calling the API at runtime (this is distinct from Authentication API errors documented above):
For responses that are 4xx error HTTP codes, where the client is authorized, the X-Error-Status-Message HTTP response HTTP header may contain a string with additional diagnostic information about the failed reasons.
Field Squared will log all failed API calls in the Integration Logs available in App Builder. You can also log all incoming and outgoing API request traffic as raw HTTP traffic for a period of up to 1 hour in the past to aid with debugging.
For a delete requests, the system will return:
- If the record is completed, the system will return HTTP 200 OK
- If the record cannot be deleted because it does not exist, the system will return HTTP 404 Not Found
For create and update requests
- if the record is created, the system will return HTTP 200 OK
- if the record exists, the system will return HTTP 200 OK
- the system will generate HTTP error code 404 Not Found only if the object being created or updated is referencing another object that exist (eg. a Task that references a User that does not exist)
Duplicate requests will be returned as HTTP 202 Accepted. This means we have already previously processed this request (because the Request-ID in the HTTP header has already been processed).
Working with Dates and Times
Date-Time values
Field Squared specifies date times using ISO-8901 dates in UTC time
YYYY-MM-DDTHH:MM:SSZ
For example 2:15pm on November 16 2016 in USA Mountain Time would be: "2016-11-16T21:15:00Z"
Date times will be localized at runtime to the time zone of each device viewing the date and times.
Dates
Dates are specified as an absolute date using year, month and day as a string.
YYYY-MM-DD
For example, November 16, 2016 would be: "2016-11-16". There is no UTC offset for dates and dates will display on all clients the same way regardless of the time zone of each client.
Times
Times in Field Squared are generally specified as absolute times with no UTC offset. The values are displayed the same way on all clients. Times are specified in hours, minutes and seconds.
HH:MM:SS
Using XML
The following sections cover some notes around using XML
Prologs and schemas
For XML, all messages are standard XML. The XML prolog and namespaces are optional. For example
<?xml version="1.0" encoding="UTF-8"?> <Authentication xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Field2Office.API.Model.Authentication"> <Email>String</Email> <Password>String</Password> </Authentication>
is treated exactly the same as
<Authentication> <Email>String</Email> <Password>String</Password> </Authentication>
XML Elements vs. Attributes
Messages should be sent with values stored in inner XML and not as attributes.
This is valid XML for the Field Squared API:
<Task> <Name>My Task</Name> <Status>Not Started</Status> </Task>
The following XML will not work with the Field Squared API as it relies on XML attributes instead of elements:
<Task name="My Task" status="Not Started">
</Task>
Empty vs. Missing vs. Properties in API Calls
Empty/NULL XML elements work differently in the Field Squared API.
The following payload means "Set Due Date to NULL".
<Task> <Name>My Task</Name> <Status>Not Started</Status> <DueDate></DueDate> </Task>
The following payload would not update the Due Date field, since it's not specified in the XML body.
<Task> <Name>My Task</Name> <Status>Not Started</Status> </Task>
Empty and NULL elements do not mean the same thing in the Field Squared API.