API Evangelist enhancements for the diaspora* API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the diaspora* API
  version: 1.0.0
  x-generated: '2026-07-20'
  x-method: generated
  x-source: >-
    Generated by the API Evangelist enrichment pipeline. Extends
    openapi/diaspora-api-openapi.yml with the cross-cutting semantics documented at
    https://diaspora.github.io/api-documentation/ that the base description does not express:
    decentralized host discovery, the scope model, the shared error envelope, pagination, and
    tag-level descriptions.
extends: ../openapi/diaspora-api-openapi.yml
actions:

- target: $.info
  description: >-
    Record the decentralization contract and the stale-banner caveat as vendor extensions so
    tooling and agents do not assume a single API host or an unstable API.
  update:
    x-decentralized: true
    x-host-discovery:
      mechanism: NodeInfo
      well_known: /.well-known/nodeinfo
      spec: http://nodeinfo.diaspora.software/
      guidance: >-
        Perform nodeinfo version discovery against the target pod before issuing any API request.
        Once a compatible version is observed, the pod can be assumed to stay compatible.
    x-auth-discovery:
      mechanism: OpenID Connect Discovery 1.0
      well_known: /.well-known/openid-configuration
    x-stability-note: >-
      The upstream documentation index still shows a banner saying the API is unstable pending
      release 0.8.0.0. That banner is stale: the API became officially supported in release
      0.9.0.0 (2024-06-16).
    x-api-evangelist:
      artifacts:
        authentication: authentication/diaspora-authentication.yml
        scopes: scopes/diaspora-scopes.yml
        errors: errors/diaspora-problem-types.yml
        conventions: conventions/diaspora-conventions.yml
        lifecycle: lifecycle/diaspora-lifecycle.yml
        data_model: data-model/diaspora-data-model.yml
        changelog: changelog/diaspora-changelog.yml

- target: $.servers[0]
  description: >-
    Clarify that the pod server variable is a required client choice rather than a default worth
    relying on, and name a couple of well-known public pods as valid values.
  update:
    x-pod-selection: >-
      The pod variable must be set to the host of the pod the authenticated user belongs to.
      diaspora.social is the default only because it is a large, reachable public pod; it is not a
      canonical API host and holds no data for users of other pods.
    x-pod-directory: https://diaspora.fediverse.observer/

- target: $.components.securitySchemes.openIdConnect
  description: >-
    Attach the dynamic client registration contract, which is the non-obvious part of integrating
    with a decentralized network and cannot be expressed in an openIdConnect scheme.
  update:
    x-dynamic-client-registration:
      supported: true
      spec: OpenID Connect Dynamic Client Registration 1.0
      endpoint_path: /api/openid_connect/clients
      method: POST
      minimal_request: [client_name, redirect_uris]
      returns: [client_id, client_secret]
      rationale: >-
        A client cannot be manually pre-registered on every pod, so it registers itself the first
        time it encounters an unknown pod.
    x-flows-supported: [authorization_code, implicit]
    x-token-transmission:
    - 'Authorization: Bearer header (preferred)'
    - access_token query parameter
    - access_token form parameter
    x-mandatory-scope: openid
    x-always-granted-scope: public:read
    x-scope-dependencies:
      private:read: [contacts:read]
      private:modify: [contacts:read]

- target: $.components.schemas.Error
  description: >-
    Flag that this envelope is not RFC 9457 and carries no stable machine-readable error
    identifier, so clients branch on status code plus operation rather than on message text.
  update:
    x-rfc9457: false
    x-media-type: application/json
    x-stable-error-identifier: false
    x-client-guidance: >-
      Do not parse the message string. Branch on HTTP status code together with the operation
      invoked. Treat 409 on interaction-create and 410 on interaction-delete as convergence to the
      desired state rather than as failures.
    x-catalog: errors/diaspora-problem-types.yml

- target: $.tags[?(@.name=='Aspects')]
  description: Describe aspects as the privacy primitive rather than as a generic grouping resource.
  update:
    description: >-
      Aspects are user-defined contact groups and the core privacy primitive of diaspora*. Every
      post is shared either publicly or with a chosen set of aspects, so aspect membership is what
      determines who can see private content.
    externalDocs:
      url: https://diaspora.github.io/api-documentation/routes/aspects.html

- target: $.tags[?(@.name=='Streams')]
  description: >-
    Record that stream contents are scope-dependent, which is unusual and easy for an integrator
    to misread as an empty result.
  update:
    description: >-
      Streams are read-only projections over posts rather than stored collections. Which posts a
      stream returns depends on the caller's granted scope set, not on request parameters alone —
      a token lacking private:read will see a materially smaller stream rather than an error.
    externalDocs:
      url: https://diaspora.github.io/api-documentation/routes/streams.html

- target: $.tags[?(@.name=='Posts')]
  description: Surface the embedded-content model of a post.
  update:
    description: >-
      Posts are the hub of the interaction graph — comments, likes and reshares are all addressed
      beneath /posts/{post_guid}. A post response may inline photos, a poll, a location, OpenGraph
      metadata, oEmbed metadata, mentioned people, and (for reshares) a root object describing the
      original post.
    externalDocs:
      url: https://diaspora.github.io/api-documentation/routes/posts.html

- target: $.paths..[?(@.responses)]
  description: >-
    Mark every operation with the pagination contract and the fact that authentication is
    universal, so generated clients and agents do not attempt anonymous calls or guess page URLs.
  update:
    x-authentication-required: true
    x-pagination:
      style: link-header
      header: Link
      rel_values: [first, previous, next, last]
      per_page_default: 20
      per_page_max: 100
      warning: >-
        Do not construct pagination URLs. Some resources page by timestamp or GUID rather than an
        integer counter. Follow the Link header.
    x-media-type: application/json