API Evangelist enhancements — Britive Services API Documentation

overlay: 1.0.0
info:
  title: API Evangelist enhancements — Britive Services API Documentation
  version: 1.0.0
extends: ./openapi/britive-services-api-openapi.yml
x-provenance:
  generated: '2026-08-08'
  method: generated
  source: openapi/_original/britive-services-api-openapi.json
  note: Records what API Evangelist changed when assembling Britive's published contract into a single document,
    plus the enhancements applied on top. The verbatim assembly of the per-operation fragments Britive publishes
    is preserved in openapi/_original/ and is never mutated.
actions:
- target: $.info
  description: Britive publishes no contact, license or termsOfService on either contract.
  update:
    x-api-evangelist-note: info.contact, info.license and info.termsOfService are absent in the source. Not synthesized
      here — recorded as a gap.
- target: $.servers[0]
  description: The published server default is the placeholder tenant test.britive-app.com, which does not resolve.
  update:
    x-api-evangelist-note: servers[0].variables.tenantURL.default is 'test.britive-app.com', which returns NXDOMAIN.
      Britive's own API prerequisites page uses demo.britive-app.com as the worked example, and that host resolves
      and serves the API. The default is left as Britive published it; this note records that it is not a callable
      host.
- target: $
  description: Type normalization applied when converting the assembled fragments into a working document.
  update:
    x-api-evangelist-normalization:
      issue: 'Britive serializes JSON booleans and numeric defaults as strings in its published fragments — "required":
        "true", "required": "false", "default": "0", "default": "20". These are invalid against the OpenAPI 3.0
        schema and break generated clients and validators.'
      occurrences_in_source: 649 across the Services API document
      action: parameter/schema boolean keywords and numeric defaults coerced to their native JSON types
      original: openapi/_original/britive-services-api-openapi.json
- target: $.components.parameters
  description: Duplicate page-size parameter component.
  update:
    x-api-evangelist-note: 'Components ''Size'' and ''PageSize'' are identical (name: size, in: query, default:
      20). One should be removed upstream.'
- target: $.paths['/api/logs/webhooks']
  description: Cross-link the derived event surface catalog.
  update:
    x-api-evangelist-see-also: asyncapi/britive-events-webhooks.yml
- target: $.components.securitySchemes
  description: The tenant OAuth 2.0 / OIDC authorization server is real but undeclared here.
  update:
    x-api-evangelist-note: Only bearerAuth is declared. Every tenant also serves RFC 8414 authorization-server metadata
      and OIDC discovery at https://{tenant}.britive-app.com/.well-known/ — see well-known/ and scopes/. No scope
      is bound to any operation.