mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-29 05:44:10 +02:00
Compare commits
10 commits
0910b46069
...
5916456346
| Author | SHA1 | Date | |
|---|---|---|---|
|
5916456346 | ||
|
|
6b5ff04d00 | ||
|
|
ce5ae4d371 | ||
|
|
27315feb17 | ||
|
|
a1c930d0d1 | ||
|
|
9e959f3922 | ||
|
|
1baf93caf5 | ||
|
|
ffc8c8edd3 | ||
|
|
35eb6e1d2b | ||
|
|
7f59715369 |
|
|
@ -257,6 +257,69 @@ 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;
|
||||
padding: 0.05rem 0.25rem;
|
||||
border-radius: 0.2rem;
|
||||
|
||||
&:hover {
|
||||
background-color: $secondary-background;
|
||||
}
|
||||
}
|
||||
|
||||
.endpoint-list .http-api-method {
|
||||
margin-right: 0.35rem;
|
||||
font-weight: $font-weight-bold;
|
||||
}
|
||||
|
||||
.endpoint-path {
|
||||
font-family: $font-family-monospace;
|
||||
color: $secondary;
|
||||
}
|
||||
|
||||
.endpoint-deprecated {
|
||||
color: $danger;
|
||||
font-weight: $font-weight-bold;
|
||||
margin-left: 0.35rem;
|
||||
}
|
||||
|
||||
.endpoint-module {
|
||||
&:not(:first-child) {
|
||||
margin-top: 0.75rem;
|
||||
}
|
||||
}
|
||||
|
||||
.endpoint-module-title {
|
||||
// font-weight: $font-weight-bold;
|
||||
font-size: 1.20rem;
|
||||
margin-bottom: 0.35rem;
|
||||
}
|
||||
}
|
||||
|
||||
.page-description {
|
||||
margin-bottom: 1rem;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
/* Styles for alert boxes */
|
||||
.alert {
|
||||
&.note {
|
||||
|
|
@ -581,4 +644,4 @@ dd {
|
|||
.breadcrumb {
|
||||
margin: 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Fix JSON formatting in the "Server admin style permissions" examples.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Push rule IDs are globally unique within their kind.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Don't advertise `creator` field in description of room creation.
|
||||
|
|
@ -1 +0,0 @@
|
|||
`room_id` is required for peeking via `/_matrix/client/v3/events`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add note to each endpoint that uses capability negotiation.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Additional OpenGraph properties can be present in URL previews.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify the special casing of membership events and redactions in power levels.
|
||||
|
|
@ -1 +0,0 @@
|
|||
`M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add `m.login.terms` to enumeration of authentication types.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add the `m.oauth` authentication type for User-Interactive Authentication as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify how to use `state_after` ahead of declaring full support for its spec version.
|
||||
|
|
@ -1 +0,0 @@
|
|||
`device_one_time_keys_count` is only optional if no unclaimed one-time keys exist.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Minor grammatical fix in the Secrets module description.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Usage of the `event_id_only` format for push notifications is not mandatory.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Swapped icon for X (fka. twitter) to updated logo in footer.
|
||||
1
changelogs/internal/newsfragments/2222.clarification
Normal file
1
changelogs/internal/newsfragments/2222.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Clarify vendor prefixing requirements.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Inline Olm & Megolm specifications.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Silence failing redocly-cli rule.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Use NPM Trusted Publishers for publishing `@matrix-org/spec` to npm.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Inline Olm & Megolm specifications.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Inline Olm & Megolm specifications.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add version picker in the navbar.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add version picker in the navbar.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add version picker in the navbar.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add version picker in the navbar.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add version picker in the navbar.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add version picker in the navbar.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add version picker in the navbar.
|
||||
|
|
@ -1 +0,0 @@
|
|||
In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room.
|
||||
|
|
@ -1 +0,0 @@
|
|||
In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send.
|
||||
|
|
@ -75,8 +75,8 @@ status = "unstable"
|
|||
current_version_url = "https://spec.matrix.org/latest"
|
||||
# The following is used when status = "stable", and is displayed in various UI elements on a released version
|
||||
# of the spec.
|
||||
# major = "1"
|
||||
# minor = "16"
|
||||
#major = "1"
|
||||
#minor = "17"
|
||||
|
||||
[[params.versions]]
|
||||
# We must include this parameter to enable docsy's version picker in the navbar. The picker
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
91
content/changelog/v1.17.md
Normal file
91
content/changelog/v1.17.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
title: v1.17 Changelog
|
||||
linkTitle: v1.17
|
||||
type: docs
|
||||
layout: changelog
|
||||
outputs:
|
||||
- html
|
||||
- checklist
|
||||
date: 2025-12-18
|
||||
---
|
||||
|
||||
## Client-Server API
|
||||
|
||||
**Removed Endpoints**
|
||||
|
||||
- Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210). ([#2186](https://github.com/matrix-org/matrix-spec/issues/2186))
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
|
||||
- Add the `m.oauth` authentication type for User-Interactive Authentication, as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312). ([#2234](https://github.com/matrix-org/matrix-spec/issues/2234))
|
||||
- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Push rule IDs are globally unique within their kind. ([#2214](https://github.com/matrix-org/matrix-spec/issues/2214))
|
||||
- Don't advertise `creator` field in description of room creation. ([#2215](https://github.com/matrix-org/matrix-spec/issues/2215))
|
||||
- `room_id` is required for peeking via `/_matrix/client/v3/events`. ([#2216](https://github.com/matrix-org/matrix-spec/issues/2216))
|
||||
- The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment. ([#2217](https://github.com/matrix-org/matrix-spec/issues/2217))
|
||||
- Add note to each endpoint that uses capability negotiation. ([#2223](https://github.com/matrix-org/matrix-spec/issues/2223))
|
||||
- Additional OpenGraph properties can be present in URL previews. ([#2225](https://github.com/matrix-org/matrix-spec/issues/2225))
|
||||
- Clarify the special casing of membership events and redactions in power levels. ([#2231](https://github.com/matrix-org/matrix-spec/issues/2231))
|
||||
- `M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code. ([#2232](https://github.com/matrix-org/matrix-spec/issues/2232))
|
||||
- Add `m.login.terms` to enumeration of authentication types. ([#2233](https://github.com/matrix-org/matrix-spec/issues/2233))
|
||||
- Clarify how to use `state_after` ahead of declaring full support for its spec version. ([#2240](https://github.com/matrix-org/matrix-spec/issues/2240))
|
||||
- `device_one_time_keys_count` is only optional if no unclaimed one-time keys exist. ([#2245](https://github.com/matrix-org/matrix-spec/issues/2245))
|
||||
- Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users. ([#2246](https://github.com/matrix-org/matrix-spec/issues/2246))
|
||||
- Usage of the `event_id_only` format for push notifications is not mandatory. ([#2255](https://github.com/matrix-org/matrix-spec/issues/2255))
|
||||
- Fix various typos throughout the specification. ([#2224](https://github.com/matrix-org/matrix-spec/issues/2224), [#2227](https://github.com/matrix-org/matrix-spec/issues/2227), [#2250](https://github.com/matrix-org/matrix-spec/issues/2250))
|
||||
|
||||
|
||||
## Server-Server API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Application Service API
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
|
||||
- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Fix JSON formatting in the "Server admin style permissions" examples. ([#2213](https://github.com/matrix-org/matrix-spec/issues/2213))
|
||||
|
||||
|
||||
## Identity Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Push Gateway API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Room Versions
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room. ([#2220](https://github.com/matrix-org/matrix-spec/issues/2220))
|
||||
- In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send. ([#2249](https://github.com/matrix-org/matrix-spec/issues/2249))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Internal Changes/Tooling
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Swapped icon for X (fka. twitter) to updated logo in footer. ([#2219](https://github.com/matrix-org/matrix-spec/issues/2219))
|
||||
- Inline Olm & Megolm specifications. ([#2226](https://github.com/matrix-org/matrix-spec/issues/2226), [#2241](https://github.com/matrix-org/matrix-spec/issues/2241), [#2242](https://github.com/matrix-org/matrix-spec/issues/2242))
|
||||
- Silence failing redocly-cli rule. ([#2238](https://github.com/matrix-org/matrix-spec/issues/2238))
|
||||
- Use NPM Trusted Publishers for publishing `@matrix-org/spec` to npm. ([#2239](https://github.com/matrix-org/matrix-spec/issues/2239))
|
||||
- Add version picker in the navbar. ([#2256](https://github.com/matrix-org/matrix-spec/issues/2256), [#2258](https://github.com/matrix-org/matrix-spec/issues/2258), [#2259](https://github.com/matrix-org/matrix-spec/issues/2259), [#2260](https://github.com/matrix-org/matrix-spec/issues/2260), [#2261](https://github.com/matrix-org/matrix-spec/issues/2261), [#2264](https://github.com/matrix-org/matrix-spec/issues/2264), [#2268](https://github.com/matrix-org/matrix-spec/issues/2268))
|
||||
- Add a list of endpoints to the top of each spec page. ([#2262](https://github.com/matrix-org/matrix-spec/issues/2262))
|
||||
|
|
@ -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 %}}
|
||||
|
|
@ -3962,42 +3962,42 @@ operations and run in a resource constrained environment. Like embedded
|
|||
applications, they are not intended to be fully-fledged communication
|
||||
systems.
|
||||
|
||||
{{% cs-module name="instant_messaging" %}}
|
||||
{{% cs-module name="rich_replies" %}}
|
||||
{{% cs-module name="voip_events" %}}
|
||||
{{% cs-module name="typing_notifications" %}}
|
||||
{{% cs-module name="receipts" %}}
|
||||
{{% cs-module name="read_markers" %}}
|
||||
{{% cs-module name="presence" %}}
|
||||
{{% cs-module name="content_repo" %}}
|
||||
{{% cs-module name="send_to_device" %}}
|
||||
{{% cs-module name="device_management" %}}
|
||||
{{% cs-module name="end_to_end_encryption" %}}
|
||||
{{% cs-module name="secrets" %}}
|
||||
{{% cs-module name="history_visibility" %}}
|
||||
{{% cs-module name="push" %}}
|
||||
{{% cs-module name="third_party_invites" %}}
|
||||
{{% cs-module name="search" %}}
|
||||
{{% cs-module name="guest_access" %}}
|
||||
{{% cs-module name="room_previews" %}}
|
||||
{{% cs-module name="tags" %}}
|
||||
{{% cs-module name="account_data" %}}
|
||||
{{% cs-module name="admin" %}}
|
||||
{{% cs-module name="event_context" %}}
|
||||
{{% cs-module name="sso_login" %}}
|
||||
{{% cs-module name="dm" %}}
|
||||
{{% cs-module name="ignore_users" %}}
|
||||
{{% cs-module name="stickers" %}}
|
||||
{{% cs-module name="report_content" %}}
|
||||
{{% cs-module name="third_party_networks" %}}
|
||||
{{% cs-module name="openid" %}}
|
||||
{{% cs-module name="server_acls" %}}
|
||||
{{% cs-module name="mentions" %}}
|
||||
{{% cs-module name="room_upgrades" %}}
|
||||
{{% cs-module name="server_notices" %}}
|
||||
{{% cs-module name="moderation_policies" %}}
|
||||
{{% cs-module name="spaces" %}}
|
||||
{{% cs-module name="event_replacements" %}}
|
||||
{{% cs-module name="event_annotations" %}}
|
||||
{{% cs-module name="threading" %}}
|
||||
{{% cs-module name="reference_relations" %}}
|
||||
{{% cs-module name="Instant Messaging" filename="instant_messaging" %}}
|
||||
{{% cs-module name="Rich replies" filename="rich_replies" %}}
|
||||
{{% cs-module name="Voice over IP" filename="voip_events" %}}
|
||||
{{% cs-module name="Typing Notifications" filename="typing_notifications" %}}
|
||||
{{% cs-module name="Receipts" filename="receipts" %}}
|
||||
{{% cs-module name="Read and unread markers" filename="read_markers" %}}
|
||||
{{% cs-module name="Presence" filename="presence" %}}
|
||||
{{% cs-module name="Content repository" filename="content_repo" %}}
|
||||
{{% cs-module name="Send-to-Device messaging" filename="send_to_device" %}}
|
||||
{{% cs-module name="Device Management" filename="device_management" %}}
|
||||
{{% cs-module name="End-to-End Encryption" filename="end_to_end_encryption" %}}
|
||||
{{% cs-module name="Secrets" filename="secrets" %}}
|
||||
{{% cs-module name="Room History Visibility" filename="history_visibility" %}}
|
||||
{{% cs-module name="Push Notifications" filename="push" %}}
|
||||
{{% cs-module name="Third-party invites" filename="third_party_invites" %}}
|
||||
{{% cs-module name="Server Side Search" filename="search" %}}
|
||||
{{% cs-module name="Guest Access" filename="guest_access" %}}
|
||||
{{% cs-module name="Room Previews" filename="room_previews" %}}
|
||||
{{% cs-module name="Room Tagging" filename="tags" %}}
|
||||
{{% cs-module name="Client Config" filename="account_data" %}}
|
||||
{{% cs-module name="Server Administration" filename="admin" %}}
|
||||
{{% cs-module name="Event Context" filename="event_context" %}}
|
||||
{{% cs-module name="SSO client login/authentication" filename="sso_login" %}}
|
||||
{{% cs-module name="Direct Messaging" filename="dm" %}}
|
||||
{{% cs-module name="Ignoring Users" filename="ignore_users" %}}
|
||||
{{% cs-module name="Sticker Messages" filename="stickers" %}}
|
||||
{{% cs-module name="Reporting Content" filename="report_content" %}}
|
||||
{{% cs-module name="Third-party Networks" filename="third_party_networks" %}}
|
||||
{{% cs-module name="OpenID" filename="openid" %}}
|
||||
{{% cs-module name="Server Access Control Lists (ACLs) for rooms" filename="server_acls" %}}
|
||||
{{% cs-module name="User and room mentions" filename="mentions" %}}
|
||||
{{% cs-module name="Room Upgrades" filename="room_upgrades" %}}
|
||||
{{% cs-module name="Server Notices" filename="server_notices" %}}
|
||||
{{% cs-module name="Moderation policy lists" filename="moderation_policies" %}}
|
||||
{{% cs-module name="Spaces" filename="spaces" %}}
|
||||
{{% cs-module name="Event replacements" filename="event_replacements" %}}
|
||||
{{% cs-module name="Event annotations and reactions" filename="event_annotations" %}}
|
||||
{{% cs-module name="Threading" filename="threading" %}}
|
||||
{{% cs-module name="Reference relations" filename="reference_relations" %}}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -408,41 +408,9 @@ development or testing data.
|
|||
that a particular MSC works) do not have to follow this process.
|
||||
|
||||
1. Have an idea for a feature.
|
||||
1. Implement the feature using unstable endpoints, vendor prefixes, and
|
||||
unstable feature flags as appropriate.
|
||||
- When using unstable endpoints, they MUST include a vendor
|
||||
prefix. For example:
|
||||
`/_matrix/client/unstable/com.example/login`. Vendor prefixes
|
||||
throughout Matrix always use the Java package naming convention.
|
||||
The MSC for the feature should identify which preferred vendor
|
||||
prefix is to be used by early adopters.
|
||||
- Note that unstable namespaces do not automatically inherit
|
||||
endpoints from stable namespaces: for example, the fact that
|
||||
`/_matrix/client/r0/sync` exists does not imply that
|
||||
`/_matrix/client/unstable/com.example/sync` exists.
|
||||
- If the client needs to be sure the server supports the feature,
|
||||
an unstable feature flag that MUST be vendor prefixed is to be
|
||||
used. This kind of flag shows up in the `unstable_features`
|
||||
section of `/versions` as, for example, `com.example.new_login`.
|
||||
The MSC for the feature should identify which preferred feature
|
||||
flag is to be used by early adopters.
|
||||
- When using this approach correctly, the implementation can
|
||||
ship/release the feature at any time, so long as the
|
||||
implementation is able to accept the technical debt that results
|
||||
from needing to provide adequate backwards and forwards
|
||||
compatibility. The implementation MUST support the flag (and
|
||||
server-side implementation) disappearing and be generally safe
|
||||
for users. Note that implementations early in the MSC review
|
||||
process may also be required to provide backwards compatibility
|
||||
with earlier editions of the proposal.
|
||||
- If the implementation cannot support the technical debt (or if
|
||||
it's impossible to provide forwards/backwards compatibility -
|
||||
e.g. a user authentication change which can't be safely rolled
|
||||
back), the implementation should not attempt to implement the
|
||||
feature and should instead wait for a spec release.
|
||||
- If at any point after early release, the idea changes in a
|
||||
backwards-incompatible way, the feature flag should also change
|
||||
so that implementations can adapt as needed.
|
||||
1. Implement the feature using [unstable endpoints, vendor prefixes, and
|
||||
unstable feature flags](#unstable-endpoints-features-and-vendor-prefixes)
|
||||
as appropriate.
|
||||
1. In parallel, or ahead of implementation, open an MSC and solicit
|
||||
review per above.
|
||||
1. Before FCP can be called, the Spec Core Team will require evidence
|
||||
|
|
@ -452,10 +420,7 @@ that a particular MSC works) do not have to follow this process.
|
|||
forwards/backwards compatibility concerns mentioned here.
|
||||
1. The FCP process is completed, and assuming nothing is flagged the
|
||||
MSC lands.
|
||||
1. Implementations can now switch to using stable prefixes
|
||||
(for example, for an endpoint, moving from
|
||||
`/unstable/org.matrix.mscxxxx/frobnicate`
|
||||
to `/v1/frobnicate`), assuming that the change
|
||||
1. Implementations can now switch to using stable prefixes, assuming that the change
|
||||
is backwards compatible with older implementations. In the rare occasion
|
||||
where backwards compatibility is not possible without a new spec release,
|
||||
implementations should continue to use unstable prefixes.
|
||||
|
|
@ -471,13 +436,6 @@ that a particular MSC works) do not have to follow this process.
|
|||
started supporting the new spec release, some noise should be raised
|
||||
in the general direction of the implementation.
|
||||
|
||||
{{% boxes/note %}}
|
||||
MSCs MUST still describe what the stable endpoints/feature looks like
|
||||
with a note towards the bottom for what the unstable feature
|
||||
flag/prefixes are. For example, an MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
|
||||
com.example/new/endpoint`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
In summary:
|
||||
|
||||
- Implementations MUST NOT use stable endpoints before the MSC has
|
||||
|
|
@ -489,14 +447,90 @@ In summary:
|
|||
- Implementations SHOULD be wary of the technical debt they are
|
||||
incurring by moving faster than the spec.
|
||||
- The vendor prefix is chosen by the developer of the feature, using
|
||||
the Java package naming convention. The foundation's preferred
|
||||
vendor prefix is `org.matrix`.
|
||||
the Java package naming convention.
|
||||
- The vendor prefixes, unstable feature flags, and unstable endpoints
|
||||
should be included in the MSC, though the MSC MUST be written in a
|
||||
way that proposes new stable endpoints. Typically this is solved by
|
||||
a small table at the bottom mapping the various values from stable
|
||||
to unstable.
|
||||
|
||||
#### Unstable endpoints, features and vendor prefixes
|
||||
|
||||
Unstable endpoints MUST use `/unstable` as the endpoint version and a
|
||||
vendor prefix in Java package naming format. For example:
|
||||
`/_matrix/client/unstable/com.example.mscxxxx/login`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Proposal authors operating with a Matrix.org Foundation mandate SHOULD use
|
||||
a vendor prefix within the `org.matrix` namespace. This namespace is otherwise
|
||||
restricted. Authors who don't own a domain MAY use the `io.github` namespace
|
||||
instead.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Note that unstable namespaces do not automatically inherit endpoints from
|
||||
stable namespaces: for example, the fact that `/_matrix/client/v3/sync`
|
||||
exists does not imply that `/_matrix/client/unstable/com.example.mscxxxx/sync`
|
||||
exists.
|
||||
|
||||
Vendor prefixes MUST also be used for:
|
||||
|
||||
- New parameters on existing endpoints. For example:
|
||||
`/_matrix/client/v3/publicRooms?com.example.mscxxxx.ordered_by=member_count`.
|
||||
- New properties in existing JSON objects. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
|
||||
"displayname": "Alice Margatroid",
|
||||
"com.example.mscxxxx.phone": [{
|
||||
"type": "landline",
|
||||
"number": "+1-206-555-7000"
|
||||
}],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
- New values for existing parameters or properties. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"errcode": "COM.EXAMPLE.MSCXXXX.M_INVALID_EMAIL",
|
||||
"error": "The email address you provided is invalid."
|
||||
}
|
||||
```
|
||||
|
||||
If the client needs to be sure the server supports the feature, an
|
||||
unstable feature flag that MUST also be vendor prefixed is to be used.
|
||||
This flag shows up in the `unstable_features` section of
|
||||
[`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
|
||||
as, for example, `com.example.mscxxxx.new_login`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
MSCs MUST still describe what the stable endpoints/feature looks like
|
||||
with a note towards the bottom for what the unstable feature
|
||||
flag/prefixes are. For example, an MSC would propose `/_matrix/client/v1/new/endpoint`,
|
||||
not `/_matrix/client/unstable/com.example.mscxxxx/new/endpoint`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When using this approach correctly, the implementation can release
|
||||
the feature at any time, so long as the implementation is able to
|
||||
accept the technical debt that results from needing to provide
|
||||
adequate backwards and forwards compatibility. The implementation
|
||||
MUST support the flag (and server-side implementation) disappearing
|
||||
and be generally safe for users. Note that implementations early in
|
||||
the MSC review process may also be required to provide backwards
|
||||
compatibility with earlier editions of the proposal.
|
||||
|
||||
If the implementation cannot support the technical debt (or if it's
|
||||
impossible to provide forwards/backwards compatibility - e.g. a user
|
||||
authentication change which can't be safely rolled back), the
|
||||
implementation should not attempt to implement the feature and should
|
||||
instead wait for a spec release.
|
||||
|
||||
If at any point after early release, the idea changes in a
|
||||
backwards-incompatible way, the feature flag should also change so
|
||||
that implementations can adapt as needed.
|
||||
|
||||
### Placeholder MSCs
|
||||
|
||||
Some proposals may contain security-sensitive or private context which can't be
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
61
layouts/_partials/endpoints-toc.html
Normal file
61
layouts/_partials/endpoints-toc.html
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
{{/*
|
||||
|
||||
Renders a list of API endpoints for the current page, given:
|
||||
|
||||
The outer page's Scratch must contain an "api_endpoints" key, which is either
|
||||
a slice of maps (a list of endpoint metadata dicts) or a map of module name ->
|
||||
slice of endpoint metadata dicts (representing the API modules and the
|
||||
endpoints they each contain). Each endpoint dict must contain the following
|
||||
keys:
|
||||
|
||||
* `anchor`: the HTML anchor for the endpoint
|
||||
* `method`: the HTTP method
|
||||
* `endpoint`: the endpoint path
|
||||
* `summary`: a short summary of the endpoint
|
||||
* `deprecated`: whether the endpoint is deprecated
|
||||
* `module`: the CS API module name, if any, for grouping purposes. If empty,
|
||||
the endpoint is considered "base" or "required".
|
||||
|
||||
*/}}
|
||||
|
||||
{{ $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 }}
|
||||
<div class="endpoints-toc mb-4">
|
||||
<details>
|
||||
<summary>List of Endpoints</summary>
|
||||
{{/* Sort by module to group visually */}}
|
||||
{{ $sorted := sort $endpoints "module" }}
|
||||
{{ $current := "" }}
|
||||
{{ range $sorted }}
|
||||
{{ $mod := .module }}
|
||||
{{/* Set a title for the base endpoints */}}
|
||||
{{ if not $mod }}{{ $mod = "Required" }}{{ end }}
|
||||
{{ if ne $mod $current }}
|
||||
{{ if $current }}</ul></div>{{ end }}
|
||||
<div class="endpoint-module">
|
||||
<div class="endpoint-module-title">{{ $mod }}</div>
|
||||
<ul class="endpoint-list">
|
||||
{{ $current = $mod }}
|
||||
{{ end }}
|
||||
{{ $key := printf "%s|%s" .method .anchor }}
|
||||
<li>
|
||||
<a href="#{{ .anchor }}">
|
||||
<span class="http-api-method">{{ .method }}</span>
|
||||
<span class="endpoint-path">{{ .endpoint }}</span>
|
||||
{{ if .deprecated }}<span class="endpoint-deprecated">(deprecated)</span>{{ end }}
|
||||
</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
{{ if $current }}</ul></div>{{ end }}
|
||||
</details>
|
||||
</div>
|
||||
{{ end }}
|
||||
|
|
@ -7,6 +7,8 @@
|
|||
of each value in `paths` to get a complete URL.
|
||||
* `anchor_base`: an optional prefix for the HTML IDs generated by
|
||||
this template.
|
||||
* `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC.
|
||||
* `module`: the current CS API module name, if any. Used to group endpoints in the TOC.
|
||||
|
||||
This template replaces the old {{*_http_api}} template.
|
||||
|
||||
|
|
@ -15,6 +17,8 @@
|
|||
{{ $api_data := index .api_data }}
|
||||
{{ $base_url := .base_url }}
|
||||
{{ $anchor_base := .anchor_base }}
|
||||
{{ $page := .page }}
|
||||
{{ $module := .module }}
|
||||
|
||||
{{ range $path_name, $path_data := $api_data.paths }}
|
||||
|
||||
|
|
@ -26,28 +30,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 "module" $module) }}
|
||||
{{ 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 "module" $module) }}
|
||||
{{ 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 "module" $module) }}
|
||||
{{ 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 "module" $module) }}
|
||||
{{ partial "openapi/render-operation" $operation_params }}
|
||||
|
||||
{{ end }}
|
||||
|
|
|
|||
|
|
@ -7,6 +7,8 @@
|
|||
* `operation_data`: the OpenAPI data for the operation
|
||||
* `anchor_base`: an optional prefix for the HTML IDs generated by
|
||||
this template.
|
||||
* `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC.
|
||||
* `module`: the current CS API module name, if any. Used to group endpoints in the TOC.
|
||||
|
||||
This template renders the operation as a `<section>` containing:
|
||||
|
||||
|
|
@ -22,6 +24,8 @@
|
|||
{{ $method := .method }}
|
||||
{{ $endpoint := .endpoint }}
|
||||
{{ $operation_data := .operation_data }}
|
||||
{{ $page := .page }}
|
||||
{{ $module := .module }}
|
||||
|
||||
{{ $anchor := "" }}
|
||||
{{ if .anchor_base }}
|
||||
|
|
@ -29,6 +33,27 @@
|
|||
{{ end }}
|
||||
{{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}
|
||||
|
||||
{{/* Collect endpoints for the on-page endpoints TOC */}}
|
||||
{{ if $page }}
|
||||
{{/* 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 "module" $module }}
|
||||
{{ if not ($page.Scratch.Get "api_endpoints_seen") }}
|
||||
{{ $page.Scratch.Set "api_endpoints_seen" dict }}
|
||||
{{ end }}
|
||||
{{/* Keep a map of seen endpoints. This is necessary as this partial may be
|
||||
rendered multiple times for the same endpoint (e.g. in the TOC and
|
||||
in the main content), leading to duplicates. */}}
|
||||
{{ $seen := $page.Scratch.Get "api_endpoints_seen" }}
|
||||
{{ $key := printf "%s|%s" $method $endpoint }}
|
||||
{{ if not (index $seen $key) }}
|
||||
{{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }}
|
||||
{{ $page.Scratch.Set "api_endpoints" (slice) }}
|
||||
{{ end }}
|
||||
{{ $page.Scratch.Add "api_endpoints" (slice $entry) }}
|
||||
{{ $page.Scratch.SetInMap "api_endpoints_seen" $key true }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
<section class="rendered-data">
|
||||
|
||||
<details {{ if not site.Params.ui.rendered_data_collapsed }}open{{ end }}>
|
||||
|
|
|
|||
14
layouts/_partials/spec-content.html
Normal file
14
layouts/_partials/spec-content.html
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
{{- /* Shared render for spec pages: title, optional description, endpoints list, body, and last-mod info. */ -}}
|
||||
<div class="td-content">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
|
||||
|
||||
{{/*
|
||||
Render an endpoints table of contents. This is the main difference
|
||||
between our templates (which call the spec-content partial) and the default
|
||||
Docsy template.
|
||||
*/}}
|
||||
{{ partial "endpoints-toc.html" . }}
|
||||
|
||||
{{ .Content }}
|
||||
</div>
|
||||
|
|
@ -3,14 +3,39 @@
|
|||
This template is used to render a Client-Server API Module. Modules are defined
|
||||
alongside the `_index.md` for the CS API.
|
||||
|
||||
The `name` parameter is the file name without extension.
|
||||
The following parameters are expected:
|
||||
|
||||
* `filename` the name of the module file to render, without extension (i.e. `spaces`).
|
||||
* `name` the display name of the module (i.e. `Spaces`).
|
||||
|
||||
*/}}
|
||||
|
||||
{{ $name := .Params.name }}
|
||||
{{ $filename := .Params.filename }}
|
||||
|
||||
{{ with .Site.GetPage "client-server-api/modules" }}
|
||||
{{ with .Resources.GetMatch (printf "%s%s" $name ".md") }}
|
||||
{{ with .Resources.GetMatch (printf "%s%s" $filename ".md") }}
|
||||
{{/* Preserve previous scratch values so nested modules don't leak */}}
|
||||
{{ $prevPage := .Scratch.Get "endpoint_page" }}
|
||||
{{ $prevModule := .Scratch.Get "endpoint_module" }}
|
||||
|
||||
{{/* Allow endpoints rendered in the module to accumulate on the parent page */}}
|
||||
{{ .Scratch.Set "endpoint_page" $.Page }}
|
||||
{{/* Name the module for grouping in the endpoints list */}}
|
||||
{{ .Scratch.Set "endpoint_module" $name }}
|
||||
|
||||
{{ .RenderShortcodes }}
|
||||
|
||||
{{/* Restore previous scratch values */}}
|
||||
{{ if $prevPage }}
|
||||
{{ .Scratch.Set "endpoint_page" $prevPage }}
|
||||
{{ else }}
|
||||
{{ .Scratch.Delete "endpoint_page" }}
|
||||
{{ end }}
|
||||
{{ if $prevModule }}
|
||||
{{ .Scratch.Set "endpoint_module" $prevModule }}
|
||||
{{ else }}
|
||||
{{ .Scratch.Delete "endpoint_module" }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
|
|
|||
|
|
@ -23,6 +23,20 @@
|
|||
{{ $api := .Params.api}}
|
||||
{{ $anchor_base := .Params.anchor_base}}
|
||||
|
||||
{{/*
|
||||
|
||||
Figure out which Page object to pass to the `openapi/render-api` partial.
|
||||
Either our own, or one stored under `endpoint_page` in the Scratch, if one
|
||||
exists.
|
||||
|
||||
*/}}
|
||||
{{ $target_page := .Page }}
|
||||
{{ with .Page.Scratch.Get "endpoint_page" }}
|
||||
{{ $target_page = . }}
|
||||
{{ end }}
|
||||
|
||||
{{ $module_name := .Page.Scratch.Get "endpoint_module" }}
|
||||
|
||||
{{ $api_data := index .Site.Data.api .Params.spec .Params.api }}
|
||||
{{ $base_url := (index $api_data.servers 0).variables.basePath.default }}
|
||||
{{ $path := delimit (slice "api" $spec $api) "/" }}
|
||||
|
|
@ -30,4 +44,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" $target_page "module" $module_name) }}
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
<div class="td-content">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
</div>
|
||||
|
|
@ -1,13 +1,19 @@
|
|||
{{/*
|
||||
|
||||
A simplified version of the list.html partial in Docsy.
|
||||
Override the `layouts/docs/list.html` template from Docsy. While this template
|
||||
is equivalent to `single.html`, it's necessary to override both templates to
|
||||
avoid falling back to the default Docsy templates.
|
||||
|
||||
https://gohugo.io/templates/types/#list
|
||||
|
||||
We use this list template to render the Client-Server API spec page and each
|
||||
of its modules.
|
||||
|
||||
The contents of the "main" block below are inserted into the `./baseof.html`
|
||||
base template.
|
||||
|
||||
*/}}
|
||||
|
||||
{{ define "main" }}
|
||||
<div class="td-content">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
|
||||
{{ .Content }}
|
||||
</div>
|
||||
{{ partial "spec-content.html" . }}
|
||||
{{ end }}
|
||||
|
|
|
|||
19
layouts/docs/single.html
Normal file
19
layouts/docs/single.html
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
{{/*
|
||||
|
||||
Override the `layouts/docs/single.html` template from Docsy. While this template
|
||||
is equivalent to `list.html`, it's necessary to override both templates to
|
||||
avoid falling back to the default Docsy templates.
|
||||
|
||||
https://gohugo.io/templates/types/#single
|
||||
|
||||
We use this single template to render the all API spec pages *except* the
|
||||
Client-Server API. The Client-Server API spec page contains modules, and thus
|
||||
is handled separately, via the `layouts/docs/list.html` template.
|
||||
|
||||
The contents of the "main" block below are inserted into the `./baseof.html`
|
||||
base template.
|
||||
|
||||
*/}}
|
||||
{{ define "main" }}
|
||||
{{ partial "spec-content.html" . }}
|
||||
{{ end }}
|
||||
Loading…
Reference in a new issue