10 API Introduction

API Introduction

General Information

• Base endpoint: localhost:8080
• All endpoints return either a JSON object or a JSON array, depending on the number of records in the response. To override this behavior, add the query parameter ?data_array=true -- the response will then always be a JSON array regardless of the number of records.
• Endpoints ending with /list always return a JSON array.

HTTP Return Codes

• HTTP 4XX return codes are used for malformed requests -- the issue is on the client side.
• HTTP 5XX return codes are used for internal errors -- the issue is on the server side. It is important NOT to treat this as a failed operation. The execution status is UNKNOWN and may have been successful.

Error Codes

• Any endpoint may return an error.
• Errors use structured codes in ERR-GGG-CCC format (e.g., ERR-401-001, ERR-400-042) where GGG is the HTTP status group and CCC is a unique sequence within that group.
• The error field is always present in error responses (since v1.2.0).

Example response:

{
  "error": {
    "code": 400,
    "error": "ERR-400-001",
    "message": "Object not found."
  }
}

The error field contains the machine-readable error code. The message field contains the localized human-readable description (language depends on the session locale). See Error Codes Reference for the full catalog of 80 platform error codes.

Endpoint Details

• For GET endpoints, parameters must be sent as a query string.
• For POST endpoints, some parameters may be sent as a query string and some as a request body:
  • When sending parameters in the request body, the following content types are supported:
    • application/x-www-form-urlencoded for query string encoding
    • multipart/form-data for HTML forms
    • application/json for JSON
• Parameters may be sent in any order.