REST API – authentication, response envelope and OpenAPI

Overview

JSON endpoints for external systems (index.php?route=api/group/resource.method). Every resource controller has an openapi(): array method; the aggregated descriptor is built from these.

Authentication

• The key arrives in the X-Oc-Api-Key header or, for backward compatibility, in the POST field api_key; the masterdata and subscription/order endpoints do not accept it as a GET parameter, the Explorer does.
• Resolution: api/auth::getUserByApiKey() → user_api_key (status=1) joined with the framework's active user → user, group, user name. If the user_api_key table is missing, every key is invalid.
• Endpoints check the function permission for the key owner with the admin route keys (canActionForUser).

Input and response

• apiInput(): GET parameters, the raw body (JSON, otherwise urlencoded) and POST fields merged; later ones override earlier ones.
• apiOut() → dlbtjson->restEnvelope(). On success the endpoint's own JSON with HTTP 200, structure unchanged. On error success:false, error (one message), error_code, and for field validation error_fields.
• HTTP status from the code (statusFor()): VALIDATION_ERROR 422, BAD_REQUEST 400, UNAUTHORIZED 401, PERMISSION_DENIED 403, NOT_FOUND 404, CONFLICT 409, DB_QUERY_ERROR, UNCAUGHT_EXCEPTION, PHP_FATAL_ERROR 500; without a code VALIDATION_ERROR.
• Every method body is in try/catch; debug_message would be added only with the debug permission, which on the catalog side is always false because the permission handler is missing there.
• Logging: successful and rejected calls go to the system log (channels api/company, api/addressmaster, api/bankaccountmaster).

OpenAPI and documentation

Known limitations

• The endpoint descriptions of the admin OpenAPI document are documentation placeholders ("Implementation status: Insufficient data to verify").
• The Explorer and admin documentation endpoints are not classified in the permission catalogue seeds.