API Evangelist enhancements for the Bonita Web REST API

# 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.
x-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.