Requests and Responses

On this page

Request headers and body

  • A call to an API route carries the bearer token, or the caller's Windows credentials when the instance uses Windows authentication.
  • A call to an API route must use HTTPS. A plain-HTTP request receives 505 HTTP Version Not Supported with the message "HTTP protocol is not supported."
  • A request whose body is multipart/* is rejected with 415 Unsupported Media Type and a message directing the caller to JSON.
  • A request whose Content-Length is above 100 KB and also above the API's configured maximum request size is rejected with 413 Request Entity Too Large, quoting both sizes. The shipped maximum request size is 50 MB. Attachment content travels as base64, so the usable file size is roughly three quarters of that. The attachment size limit is a separate setting held in the database: GET /V1/SystemSettings returns it in megabytes, or 0 when the attachment limit is switched off. Check that value before uploading; the request size limit is separate and larger.
  • A trailing slash on the path is ignored: .../Profile and .../Profile/ are the same route.
  • Query-string values reach the product already decoded, and a + is read as a space. Percent-encode spaces, &, =, #, +, and % in a value.
  • The response is JSON unless the request's Accept header asks for XML. In XML, the envelope's root element is Result.

The two token endpoints are outside these checks: the HTTPS, media type, and body size refusals and the choice between JSON and XML do not apply to them. A token request of an unsupported content type is refused with a plain-text 400 answer instead.

The response envelope

A call that reaches one of the API's JSON routes answers the same four-field envelope, whether the call succeeded or failed:

Field Meaning
success Whether the call succeeded.
errorCode 0 on success, 101 on failure. There is no other value, so errorCode cannot tell failures apart; the distinguishing information is in errorText.
errorText The error message when the call failed.
responseObject The result of the call. It is null when the call failed with an error; when a workflow action aborts, it still carries the action's messages (see Workflow actions that abort).

A failed call on these routes still answers with HTTP status 200, so branch on success, not on the HTTP status code.

Answers that do not use the envelope include:

  • the 415, 413, and 505 refusals described above, which are sent before the call runs;
  • a request the API refuses as unauthorized, which gets the web framework's own unauthorized answer (401);
  • the token endpoints, including a token answer, a refused grant, and the plain-text 400 answer to a token request of an unsupported content type;
  • the lifecycle routes;
  • the root page, which is an HTML page;
  • attachment downloads;
  • the route that runs an action from a signed link, which renders an HTML page;
  • V1/ai-response, App/RenewAIControl, and Ssp/RenewAIControl;
  • V1/get-file.

On an instance that uses Windows authentication, no token endpoint exists, and a POST to /token answers with the envelope, saying that access-token authentication is not configured.

Workflow actions that abort

When a workflow action is aborted while it runs and leaves at least one message, the call reports success: false and copies only the last message into errorText. The full message list stays in responseObject.MessageList. If the last message is empty, or the abort leaves no message, success stays true and only responseObject.Succeed is false.

A refusal before the action runs - an unavailable action, an action of the wrong kind, a missing object, the action's condition not being met, or an unknown or mandatory field - comes back as an ordinary failure, with responseObject set to null and no message list.

Errors

errorText is the message of the underlying error, passed through as written. The API's error strings include unknown field, mandatory field, unknown attachment area, invalid operation, action condition not satisfied, object not found, inactive object, and impersonation not allowed for a given method. The text is stable enough to log, but it is not a contract to parse. When the error has an inner error, errorText contains both messages, the inner one appended after a space.

An ordinary rule failure, such as an unmet action condition or an unknown field, is returned to the caller in errorText but is not, by itself, written to the API's log as a fatal error.

Date and time format

Date and date-time values in record fields, view columns, query filter values, and action-form fields are converted against the API instance's configured time zone, so every API client sees the same time zone whatever the technician's locale. The Admin Center shows this setting on the API instance's Timezone tab (see API Settings). When no time zone is set, the API uses the Windows time zone of the machine it runs on. In that case, the Timezone tab shows the time zone of the Admin Center's host, which can differ from the API's.

On input, a value is accepted in one of these forms:

  • a date, yyyy-mm-dd;
  • a date-time in UTC, ending in Z;
  • a date-time with a ±hh:nn offset.

A date-time value with no time zone is refused with Invalid date/time format "<value>". A value with a time zone is shifted to the configured time zone's local time before it is stored.

On output, a date-time field is written as yyyy-mm-ddThh:nn:ss±hh:nn: the stored clock time followed by the offset the configured time zone has at that moment, daylight saving time included. A date-only field is written as yyyy-mm-dd with no offset.

The conversion assumes that stored values were written in the configured time zone; with any other time zone, API values do not agree with the database. If the configured time zone name is not a known Windows time zone, nothing is converted: output carries +00:00, and input is stored as UTC. When no time zone is set and the Windows time zone of the API's host cannot be found in the machine's list of time zones, nothing is converted either. The modification stamp an action form carries is written with no time zone conversion.

  • Objects and Fields - which classes the API exposes and how to refer to fields, including HTML fields.
  • API Settings - the API instance's settings in the Admin Center, including its time zone.