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