Shared API Integration Guide

This guide provides a comprehensive introduction to integrating with the AppBuilder public API engine. AppBuilder-based applications use a unified API architecture, authentication model, and payload schema.

🔌 API Architecture (JSON-RPC 2.0)

All AppBuilder APIs communicate over HTTP/S using a modified JSON-RPC 2.0 protocol. Rather than exposing multiple REST resource endpoints, the application exposes a single HTTP POST endpoint:

POST https://.com/api/rpc

Request Payload Shape

To call an API method, send a JSON object containing the method string and the argument key-value params object:

{
  "method": "ClassRpc.methodName",
  "params": {
    "subscriptionId": "sub_94821",
    "paramName": "value"
  }
}

Response Payload Shapes

🟢 Success Response (`2xx` status codes)

If the method executes successfully, the result is returned under the result key:

{
  "result": {
    "success": true,
    "data": { ... }
  }
}

🔴 Error Response (`4xx` or `5xx` status codes)

If the method fails (due to invalid parameters, unauthorized access, or internal server exceptions), the error details are returned under the error key:

{
  "error": {
    "code": "ERROR_CODE_STRING",
    "message": "Human-readable explanation of what went wrong.",
    "details": {
      "validationErrors": [ ... ]
    }
  }
}

🔑 Authentication (API Keys)

To authenticate your requests:

Generate an API Key under Settings -> Admin -> API Keys inside the target application.
Include the key in the x-api-key HTTP header in all outbound requests.

Request Headers Example

POST /api/rpc HTTP/1.1
Host: api.your-application.com
Content-Type: application/json
x-api-key: ak_live_3892189a8c71b9...

Caution

API Key Security: Treat your API keys as sensitive secrets. Never commit them to client-side code repositories, push them to public version control, or expose them directly in web browsers. Always relay key-based calls through a secure backend proxy.

🏢 Subscription Scoping

AppBuilder supports enterprise multi-tenancy. Most write and query methods require a subscriptionId parameter inside the params object to scope data permissions:

{
  "method": "ClassRpc.methodName",
  "params": {
    "subscriptionId": "sub_workspace_01",
    "dataField": "..."
  }
}

Requests using API keys that do not belong to the target subscriptionId will return a FORBIDDEN error.

🛡️ General System Error Codes

The following cross-cutting error codes can be returned by any endpoint inside the system:

Error Code	HTTP Status	Description	Recovery Step
`UNAUTHORIZED`	`401`	The `x-api-key` header is missing, malformed, or invalid.	Verify that the API Key header is set correctly and is active.
`FORBIDDEN`	`403`	The authenticated key lacks permission to access the method or target subscription resources.	Check workspace user role permissions or key scope settings.
`METHOD_NOT_FOUND`	`404`	The requested `method` does not exist or has been disabled.	Double check spelling, casing, or API class prefixes.
`INVALID_PARAMS`	`400`	Parameter validation failed.	Check the response `error.details` for missing or malformed keys.
`RATE_LIMIT_EXCEEDED`	`429`	Requests exceeded the allocated tier quota.	Throttle client requests. Inspect the `Retry-After` header.
`INTERNAL_ERROR`	`500`	An unhandled server-side exception occurred.	Retry the request with exponential backoff. Contact system support.

📚 API Reference Discovery

For individual application schemas, method signatures, parameter tables, and specific integration examples, consult the respective application's API endpoint index:

Endpoints — Detailed list of all RPC methods, parameters, request/response models, and cURL examples for this application.