Handle API requests, responses and errors
Use the right method and body type, distinguish response shapes and validate success beyond HTTP 200.
IFBI endpoints do not all return the same JSON envelope. Read the response schema for each operation before building a shared client helper.
Recognise the response shape
| Operation | Response shape to expect |
|---|---|
POST /api/token | Plain token object, including access_token. |
GET /api/Dataset/All | Bare array. |
GET /api/Dashboard/All | Object containing the dashboard array in Data. |
GET /api/Canvas/{id} | Bare canvas object. |
POST /api/Kpi/Result | Wrapped result whose Data is a string. |
POST /api/Canvas/SetFavoriteForUser | HTTP 200 can have no response body. |
POST /api/Dataset/Save | Bare string: a saved GUID or a worksheet-failure message. |
For wrapped responses, inspect IsError when present before using Data. Preserve the distinction between an empty array, a null result and an empty response body. A helper that unconditionally reads body.Data or unconditionally parses JSON will fail on valid responses.
Treat dataset save as a special case
Dataset Save can return HTTP 200 for an Excel worksheet failure. Parse the returned string as a GUID to establish success. A non-GUID string is a failure, even though the HTTP status is 200. Duplicate dataset names can produce HTTP 400.
Send the documented request type
Token requests use application/x-www-form-urlencoded. Most model-based operations use JSON. Dashboard definition import uses multipart file parts. Dataset import instead sends a JSON object containing datasetJson as a JSON-encoded string, along with connection identifiers.
Methods matter. Some documented GET routes perform changes, including certain delete or duplicate operations. Classify requests by their effect when deciding whether a retry is safe.
Respond to errors at the right layer
HTTP 400 usually calls for correcting the request or resource configuration. HTTP 401 can indicate authentication or an applicable authorisation filter; inspect the response and identity rather than assuming every 401 is expiry. HTTP 403 can be returned by the installation licensing filter. HTTP 500 requires investigation of the operation and server-side evidence.
Keep detailed error bodies in restricted diagnostics. They may include paths, connection information or exception details. Return a useful, limited message to your application’s users.
Continue with reliable integration behaviour or troubleshooting.
Updated 3 days ago