From 82a67a1fabe747c63d9228e9c1b488cd46b353f1 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 5 Dec 2025 15:11:17 +0000 Subject: [PATCH 1/6] Store each endpoint's metadata in a slice on Page Such that we can later construct the table of contents with the data. --- layouts/_partials/openapi/render-api.html | 9 +++++---- layouts/_partials/openapi/render-operation.html | 11 +++++++++++ layouts/_shortcodes/http-api.html | 2 +- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/layouts/_partials/openapi/render-api.html b/layouts/_partials/openapi/render-api.html index 608cfa33..a40fb04a 100644 --- a/layouts/_partials/openapi/render-api.html +++ b/layouts/_partials/openapi/render-api.html @@ -15,6 +15,7 @@ {{ $api_data := index .api_data }} {{ $base_url := .base_url }} {{ $anchor_base := .anchor_base }} +{{ $page := .page }} {{ range $path_name, $path_data := $api_data.paths }} @@ -26,28 +27,28 @@ {{ with $path_data.get }} - {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base "page" $page) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.post }} - {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base "page" $page) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.put }} - {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base "page" $page) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.delete }} - {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base "page" $page) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} diff --git a/layouts/_partials/openapi/render-operation.html b/layouts/_partials/openapi/render-operation.html index c1e34ddf..d59ea16d 100644 --- a/layouts/_partials/openapi/render-operation.html +++ b/layouts/_partials/openapi/render-operation.html @@ -22,6 +22,7 @@ {{ $method := .method }} {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} +{{ $page := .page }} {{ $anchor := "" }} {{ if .anchor_base }} @@ -29,6 +30,16 @@ {{ end }} {{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }} +{{/* Collect endpoints for the on-page endpoints TOC */}} +{{ if $page }} + {{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary }} + {{/* Store each endpoint's metadata in a scratch variable */}} + {{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }} + {{ $page.Scratch.Set "api_endpoints" (slice) }} + {{ end }} + {{ $page.Scratch.Add "api_endpoints" (slice $entry) }} +{{ end }} +
diff --git a/layouts/_shortcodes/http-api.html b/layouts/_shortcodes/http-api.html index b5201c49..dc2b7d02 100644 --- a/layouts/_shortcodes/http-api.html +++ b/layouts/_shortcodes/http-api.html @@ -30,4 +30,4 @@ {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }} {{ $api_data = partial "json-schema/resolve-allof" $api_data }} -{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base) }} +{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base "page" .Page) }} From 56d48eb3a8e6ca57e84f3688de1b811362c62efc Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 5 Dec 2025 15:12:15 +0000 Subject: [PATCH 2/6] Add an endpoints table of contents A simple list of endpoints that one can ctrl-f through. --- assets/scss/_styles_project.scss | 41 +++++++++++++++++++++++++++- layouts/_partials/endpoints-toc.html | 28 +++++++++++++++++++ layouts/docs/list.html | 3 +- 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 layouts/_partials/endpoints-toc.html diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index ce0ce0ee..71686e54 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -257,6 +257,45 @@ Custom SCSS for the Matrix spec } +.endpoints-toc { + summary { + cursor: pointer; + font-weight: $font-weight-bold; + font-size: 1.05rem; + margin-bottom: 0.5rem; + } + + .endpoint-list { + list-style: none; + padding-left: 0; + margin: 0; + } + + .endpoint-list li { + margin: 0.2rem 0; + } + + .endpoint-list a { + text-decoration: none; + color: inherit; + } + + .endpoint-list .http-api-method { + font-weight: $font-weight-bold; + margin-right: 0.35rem; + } + + .endpoint-path { + font-family: $font-family-monospace; + color: $secondary; + } +} + +.page-description { + margin-bottom: 1rem; + color: inherit; +} + /* Styles for alert boxes */ .alert { &.note { @@ -581,4 +620,4 @@ dd { .breadcrumb { margin: 0; } -} \ No newline at end of file +} diff --git a/layouts/_partials/endpoints-toc.html b/layouts/_partials/endpoints-toc.html new file mode 100644 index 00000000..238dee05 --- /dev/null +++ b/layouts/_partials/endpoints-toc.html @@ -0,0 +1,28 @@ +{{/* Minimal list of API endpoints for the current page. */}} +{{ $raw := .Scratch.Get "api_endpoints" }} +{{/* Normalize to a slice */}} +{{ $endpoints := slice }} +{{ if reflect.IsSlice $raw }} + {{ $endpoints = $raw }} +{{ else if reflect.IsMap $raw }} + {{ range $raw }} + {{ $endpoints = append $endpoints . }} + {{ end }} +{{ end }} +{{ if gt (len $endpoints) 0 }} +
+
+ List of Endpoints + +
+
+{{ end }} diff --git a/layouts/docs/list.html b/layouts/docs/list.html index 01145138..25449816 100644 --- a/layouts/docs/list.html +++ b/layouts/docs/list.html @@ -7,7 +7,8 @@ {{ define "main" }}

{{ .Title }}

- {{ with .Params.description }}
{{ . | markdownify }}
{{ end }} + {{ with .Params.description }}

{{ . | markdownify }}

{{ end }} + {{ partial "endpoints-toc.html" . }} {{ .Content }}
{{ end }} From f03730455dccd890bd1cb5003f3ed2a53d0cccfc Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 5 Dec 2025 15:46:03 +0000 Subject: [PATCH 3/6] Place the endpoints list just under the description of each API We needed to override Docsy's default page renderers to show it. Because the Client-Server API uses a different render chain than the other endpoint pages, we have to override two of Docsy's pages (`content.html` and `single.html`). In order to reduce duplication, we then put the shared content into a `spec-content.html` partial. --- layouts/_partials/spec-content.html | 9 +++++++++ layouts/content.html | 7 +++---- layouts/docs/single.html | 3 +++ 3 files changed, 15 insertions(+), 4 deletions(-) create mode 100644 layouts/_partials/spec-content.html create mode 100644 layouts/docs/single.html diff --git a/layouts/_partials/spec-content.html b/layouts/_partials/spec-content.html new file mode 100644 index 00000000..21596dc5 --- /dev/null +++ b/layouts/_partials/spec-content.html @@ -0,0 +1,9 @@ +{{- /* Shared render for spec pages: title, optional description, endpoints list, body, and last-mod info. */ -}} +
+

{{ .Title }}

+ {{ partial "endpoints-toc.html" . }} + + {{ .Content }} + + {{ partial "page-meta-lastmod.html" . }} +
diff --git a/layouts/content.html b/layouts/content.html index e58073f3..1fde0699 100644 --- a/layouts/content.html +++ b/layouts/content.html @@ -1,4 +1,3 @@ -
-

{{ .Title }}

- {{ .Content }} -
+{{ define "main" }} + {{ partial "spec-content.html" . }} +{{ end }} diff --git a/layouts/docs/single.html b/layouts/docs/single.html new file mode 100644 index 00000000..1fde0699 --- /dev/null +++ b/layouts/docs/single.html @@ -0,0 +1,3 @@ +{{ define "main" }} + {{ partial "spec-content.html" . }} +{{ end }} From 1213f81676321a39641814369cf5faead3ea9e79 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 5 Dec 2025 15:47:08 +0000 Subject: [PATCH 4/6] Move each spec's intro above the endpoints list This just looks visually nicer. You have an introduction paragraph, then the list of endpoints, then the spec. --- content/application-service-api.md | 14 +++-- content/client-server-api/_index.md | 12 ++--- content/identity-service-api.md | 16 +++--- content/push-gateway-api.md | 7 ++- content/server-server-api.md | 79 ++++++++++++++--------------- layouts/_partials/spec-content.html | 2 + 6 files changed, 62 insertions(+), 68 deletions(-) diff --git a/content/application-service-api.md b/content/application-service-api.md index cc2c25ca..83217383 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -2,16 +2,14 @@ title: "Application Service API" weight: 30 type: docs +description: | + The Matrix client-server API and server-server APIs provide a consistent, + self-contained federated messaging fabric but leave little room for custom + server-side behaviour such as gateways, filters, or extensible hooks. The + Application Service API defines a standard way to add this extensible + functionality, independent of the underlying homeserver implementation. --- -The Matrix client-server API and server-server APIs provide the means to -implement a consistent self-contained federated messaging fabric. -However, they provide limited means of implementing custom server-side -behaviour in Matrix (e.g. gateways, filters, extensible hooks etc). The -Application Service API (AS API) defines a standard API to allow such -extensible functionality to be implemented irrespective of the -underlying homeserver implementation. - ## Application Services Application services are passive and can only observe events from the diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2460776f..82d05b4f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2,14 +2,14 @@ title: "Client-Server API" weight: 10 type: docs +description: | + The client-server API allows clients to send messages, control rooms and + synchronise conversation history. It is designed to support both lightweight + clients which store no state and lazy-load data from the server as required, + as well as heavyweight clients which maintain a full local persistent copy of + server state. --- -The client-server API allows clients to -send messages, control rooms and synchronise conversation history. It is -designed to support both lightweight clients which store no state and -lazy-load data from the server as required - as well as heavyweight -clients which maintain a full local persistent copy of server state. - ## API Standards {{% boxes/note %}} diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 3c20a12a..8946ad34 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -2,17 +2,15 @@ title: "Identity Service API" weight: 40 type: docs +description: | + The Matrix client-server and server-server APIs are largely expressed in + Matrix user identifiers. Sometimes it is useful to refer to users by other + (“third-party”) identifiers such as email addresses or phone numbers. The + Identity Service API describes how mappings between 3PIDs and Matrix user + IDs can be established, validated, and used; in practice this has been + applied to email addresses and phone numbers. --- -The Matrix client-server and server-server APIs are largely expressed in -Matrix user identifiers. From time to time, it is useful to refer to -users by other ("third-party") identifiers, or "3PID"s, e.g. their email -address or phone number. This Identity Service Specification describes -how mappings between third-party identifiers and Matrix user identifiers -can be established, validated, and used. This description technically -may apply to any 3PID, but in practice has only been applied -specifically to email addresses and phone numbers. - ## General principles The purpose of an identity server is to validate, store, and answer diff --git a/content/push-gateway-api.md b/content/push-gateway-api.md index 161cf24f..f74decd9 100644 --- a/content/push-gateway-api.md +++ b/content/push-gateway-api.md @@ -2,12 +2,11 @@ title: "Push Gateway API" weight: 50 type: docs +description: | + Clients may want to receive push notifications when events are received at the + homeserver. This is managed by a distinct entity called the Push Gateway. --- -Clients may want to receive push notifications when events are received -at the homeserver. This is managed by a distinct entity called the Push -Gateway. - ## Overview A client's homeserver forwards information about received events to the diff --git a/content/server-server-api.md b/content/server-server-api.md index ca1cdd2e..1ab7e3ba 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -2,49 +2,46 @@ title: "Server-Server API" weight: 20 type: docs +description: | + Matrix homeservers use the Federation APIs (also known as server-server APIs) + to communicate with each other. Homeservers use these APIs to push messages in + real-time, retrieve historic messages, and query profile or presence + information about users on other servers. The APIs are implemented over HTTPS, + with authentication provided by public key signatures both at the TLS + transport layer and in HTTP Authorization headers. + + There are three main kinds of communication that occur between + homeservers: + + Persistent Data Units (PDUs): + These events are broadcast from one homeserver to any others that have + joined the same room (identified by Room ID). They are persisted in + long-term storage and record the history of messages and state for a + room. + + Like email, it is the responsibility of the originating server of a PDU + to deliver that event to its recipient servers. However PDUs are signed + using the originating server's private key so that it is possible to + deliver them through third-party servers. + + Ephemeral Data Units (EDUs): + These events are pushed between pairs of homeservers. They are not + persisted and are not part of the history of a room, nor does the + receiving homeserver have to reply to them. + + Queries: + These are single request/response interactions between a given pair of + servers, initiated by one side sending an HTTPS GET request to obtain + some information, and responded by the other. They are not persisted and + contain no long-term significant history. They simply request a snapshot + state at the instant the query is made. + + EDUs and PDUs are further wrapped in an envelope called a Transaction, + which is transferred from the origin to the destination homeserver using + an HTTPS PUT request. + --- -Matrix homeservers use the Federation APIs (also known as server-server -APIs) to communicate with each other. Homeservers use these APIs to push -messages to each other in real-time, to retrieve historic messages from -each other, and to query profile and presence information about users on -each other's servers. - -The APIs are implemented using HTTPS requests between each of the -servers. These HTTPS requests are strongly authenticated using public -key signatures at the TLS transport layer and using public key -signatures in HTTP Authorization headers at the HTTP layer. - -There are three main kinds of communication that occur between -homeservers: - -Persistent Data Units (PDUs): -These events are broadcast from one homeserver to any others that have -joined the same room (identified by Room ID). They are persisted in -long-term storage and record the history of messages and state for a -room. - -Like email, it is the responsibility of the originating server of a PDU -to deliver that event to its recipient servers. However PDUs are signed -using the originating server's private key so that it is possible to -deliver them through third-party servers. - -Ephemeral Data Units (EDUs): -These events are pushed between pairs of homeservers. They are not -persisted and are not part of the history of a room, nor does the -receiving homeserver have to reply to them. - -Queries: -These are single request/response interactions between a given pair of -servers, initiated by one side sending an HTTPS GET request to obtain -some information, and responded by the other. They are not persisted and -contain no long-term significant history. They simply request a snapshot -state at the instant the query is made. - -EDUs and PDUs are further wrapped in an envelope called a Transaction, -which is transferred from the origin to the destination homeserver using -an HTTPS PUT request. - ## API standards The mandatory baseline for server-server communication in Matrix is diff --git a/layouts/_partials/spec-content.html b/layouts/_partials/spec-content.html index 21596dc5..7f18c60a 100644 --- a/layouts/_partials/spec-content.html +++ b/layouts/_partials/spec-content.html @@ -1,6 +1,8 @@ {{- /* Shared render for spec pages: title, optional description, endpoints list, body, and last-mod info. */ -}}

{{ .Title }}

+ {{ with .Params.description }}

{{ . | markdownify }}

{{ end }} + {{ partial "endpoints-toc.html" . }} {{ .Content }} From 17acd978a40d1f26729782a61c810dbbef672663 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 5 Dec 2025 14:53:10 +0000 Subject: [PATCH 5/6] Display "(deprecated)" next to deprecated endpoints --- assets/scss/_styles_project.scss | 6 ++++++ layouts/_partials/endpoints-toc.html | 1 + layouts/_partials/openapi/render-operation.html | 2 +- 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 71686e54..2e1d2da9 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -289,6 +289,12 @@ Custom SCSS for the Matrix spec font-family: $font-family-monospace; color: $secondary; } + + .endpoint-deprecated { + color: $danger; + font-weight: $font-weight-bold; + margin-left: 0.35rem; + } } .page-description { diff --git a/layouts/_partials/endpoints-toc.html b/layouts/_partials/endpoints-toc.html index 238dee05..f2ccae3b 100644 --- a/layouts/_partials/endpoints-toc.html +++ b/layouts/_partials/endpoints-toc.html @@ -19,6 +19,7 @@ {{ .method }} {{ .endpoint }} + {{ if .deprecated }}(deprecated){{ end }} {{ end }} diff --git a/layouts/_partials/openapi/render-operation.html b/layouts/_partials/openapi/render-operation.html index d59ea16d..dbfdf346 100644 --- a/layouts/_partials/openapi/render-operation.html +++ b/layouts/_partials/openapi/render-operation.html @@ -32,8 +32,8 @@ {{/* Collect endpoints for the on-page endpoints TOC */}} {{ if $page }} - {{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary }} {{/* Store each endpoint's metadata in a scratch variable */}} + {{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary "deprecated" $operation_data.deprecated }} {{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }} {{ $page.Scratch.Set "api_endpoints" (slice) }} {{ end }} From 42a1bc370f4c2892dca5fc164657237866e2cc4e Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 5 Dec 2025 15:57:28 +0000 Subject: [PATCH 6/6] newsfile --- changelogs/internal/newsfragments/2262.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/internal/newsfragments/2262.clarification diff --git a/changelogs/internal/newsfragments/2262.clarification b/changelogs/internal/newsfragments/2262.clarification new file mode 100644 index 00000000..117c2bec --- /dev/null +++ b/changelogs/internal/newsfragments/2262.clarification @@ -0,0 +1 @@ +Add a list of endpoints to the top of each spec page. \ No newline at end of file