# authorship: generated by API Evangelist tooling. Stamped 2026-08-18 # on the file's own generator header (roadmap#64). An unmarked file is # NOT assumed to be ours -- absence of evidence was never stamped. method: generated overlay: 1.0.0 info: title: API Evangelist enhancements for the Bonita Web REST API version: 1.0.0 extends: openapi/bonitasoft-bonita-openapi.yml x-generated: '2026-08-17' x-method: generated x-source: >- Generated by the API Evangelist enrichment pipeline from the verbatim Bonita API 1.0.9 document harvested at https://api-documentation.ofelia.com/latest/openapi.yaml. The harvested spec is never mutated; every observation this pipeline made about it is expressed here as an Overlay action instead. x-note: >- These actions add discovery metadata and record findings. They do NOT change paths, operations, schemas, parameters or security. Applying this overlay is safe and reversible. actions: # --- provider identity and provenance --- - target: $.info update: x-apievangelist-provider: bonitasoft x-apievangelist-provider-name: Bonitasoft x-apievangelist-current-brand: Ofelia x-apievangelist-rebrand-date: '2026-06-09' x-apievangelist-harvested: '2026-08-17' x-apievangelist-harvested-from: https://api-documentation.ofelia.com/latest/openapi.yaml x-apievangelist-spec-version: 1.0.9 x-apievangelist-spec-released: '2026-06-19' x-apievangelist-source-of-truth: https://github.com/bonitasoft/bonita-openapi x-apievangelist-license: GPL-2.0 x-apievangelist-postman: https://api-documentation.ofelia.com/latest/postman.json x-apievangelist-reference: https://api-documentation.ofelia.com/latest/ x-apievangelist-ownership-basis: >- Served from the provider's own api-documentation.ofelia.com host, byte identical to the bonita-openapi-1.0.9.yaml release asset on github.com/bonitasoft/bonita-openapi. info.title "Bonita API", info.license GPL-2.0, and the description links to github.com/bonitasoft/bonita-java-client and the org.bonitasoft.web Maven group. First-party beyond doubt. # --- deployment model: the servers[] block needs explaining, not replacing --- - target: $.servers update: x-apievangelist-deployment-model: >- Bonita is self-hosted software. The declared server http://localhost:8080/bonita is the vendor's own labelled sample for a local development instance and is CORRECT as published — there is no vendor-operated production host to substitute. Real bases: Bonita Cloud production https://{customer-name}.bonitacloud.com/bonita, Bonita Cloud non-production https://{customer-name}-integration.bonitacloud.com/bonita, on-premises {scheme}://{host}:{port}/bonita. Documented at https://documentation.ofelia.com/cloud/latest/manage/url-customization. x-apievangelist-do-not-repair: >- Do NOT rewrite this servers[] block to a concrete host. A localhost server here is a true statement about a self-hosted product, not a placeholder defect. # --- runtime semantics OpenAPI cannot express --- - target: $.info update: x-apievangelist-conventions: conventions/bonitasoft-conventions.yml x-apievangelist-authentication: authentication/bonitasoft-authentication.yml x-apievangelist-errors: errors/bonitasoft-problem-types.yml x-apievangelist-rate-limits: rate-limits/bonitasoft-rate-limits.yml x-apievangelist-lifecycle: lifecycle/bonitasoft-lifecycle.yml x-apievangelist-data-model: data-model/bonitasoft-data-model.yml x-apievangelist-sandbox: sandbox/bonitasoft-sandbox.yml x-apievangelist-skills: skills/_index.yml - target: $.info update: x-apievangelist-idempotency: supported: false finding: >- No idempotency-key header, parameter or documented convention exists in any of the 224 operations. Retrying POST /API/bpm/case creates a second case. Recorded so no downstream consumer infers idempotency from the presence of a Conventions artifact. x-apievangelist-error-format: rfc9457: false envelope: '{ "message": string }' finding: >- Errors are declared consistently (401/403/5XX on all 224 operations, 400 on 219) but carry no machine-readable code or type URI. Adopting RFC 9457 would be a change to components.schemas.Error alone. x-apievangelist-pagination: style: offset params: {index: p, size: c, order: o, filter: f, search: s} state_location: content-range response header finding: >- p and c are `required: true`, so an unparameterised list call returns 400 rather than a default first page. This surprises most generated clients. x-apievangelist-undeclared-parameter: name: d purpose: repeatable field-expansion ("deploy") parameter example: /API/bpm/flowNode/143?d=processId&d=caseId&d=assigned_id finding: >- Documented in info.description prose but NOT declared in any operation's parameters[], so it is invisible to code generators and to any agent reading only the machine-readable contract. The single highest-value fix available to this spec. x-apievangelist-archive-duality: finding: >- Nearly every runtime resource has an archived twin (archivedCase, archivedTask, archivedHumanTask, archivedFlowNode, archivedActivity, archivedCaseVariable, archivedCaseDocument, archivedComment, archivedConnectorInstance). Completed work 404s on the live resource and must be read from the archive, joined by sourceObjectId. Nothing in the spec links a live resource to its archived counterpart. x-apievangelist-examples-coverage: operations_with_x_codesamples: 7 of_total: 224 percent: 3 languages: [Shell] inline_example_blocks: 23 finding: >- Only 7 of 224 operations carry an x-codeSamples block, all of them curl, and they cluster on the authentication and session operations. 23 inline request/response example blocks exist elsewhere. No examples/ artifact was generated for this provider because seven curl snippets already captured in sandbox/bonitasoft-sandbox.yml are the whole set — extracting them into a second file would duplicate rather than add. Recorded as a gap: an API with 224 operations and a 162-schema model would benefit most from per-resource request/response examples. x-apievangelist-spec-typo: paths: - /API/bpm/achivedFailure/flowNode/{flowNodeInstanceId} - /API/bpm/achivedFailure/case/{caseId} - /API/bpm/achivedFailure/case/{rootCaseId}/childCases finding: >- Spelled "achivedFailure", missing the r, while every other archived resource uses "archived". Reported, not corrected — only Bonitasoft can say whether the runtime serves the typo. - target: $.components.securitySchemes update: x-apievangelist-model: >- Session + CSRF, not API keys or OAuth. bonita_auth is the JSESSIONID cookie from POST /loginservice; bonita_token is the X-Bonita-API-Token CSRF header required on POST/PUT/DELETE and read from the cookie of the most recent successful login; bearer_auth applies only when an Enterprise runtime is configured for OIDC SSO. x-apievangelist-authorization-model: >- Profile/permission based, NOT OAuth scopes. Endpoints map to permissions and permissions to profiles (User, Administrator, Super Administrator), with static and dynamic authorization checks enabled by default. This is why no OAuthScopes artifact exists for this provider. x-apievangelist-docs: https://documentation.ofelia.com/bonita/latest/identity/rest-api-authorization # --- deprecation posture --- - target: $.info update: x-apievangelist-deprecation: policy_published: false deprecated_operations: 33 of_total: 224 clusters: - Legacy Application / ApplicationMenu / ApplicationPage writes - Profile / ProfileEntry / Theme writes - Design-time process and BDM writes (createProcess, uploadProcess, installBDM) finding: >- Deprecation is marked in the CONTRACT but no policy, sunset date or replacement is published anywhere, and no Sunset/Deprecation response header (RFC 8594) is declared. A machine can see what is deprecated; a human cannot find out when it goes away. # --- what is absent, recorded once so nobody re-derives it --- - target: $.info update: x-apievangelist-absent-surfaces: mcp_server: false a2a_agent_card: false llms_txt: false well_known_documents: false graphql: false asyncapi: false webhooks: false status_page: false security_txt: false oauth_scopes: false note: >- Each of these was probed on 2026-08-17 and missed. asyncapi/webhooks are not-applicable rather than missing: Bonita's events are internal BPMN message, signal and timer events that a caller POSTs to, not deliveries a subscriber receives.