mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-20 09:54:10 +02:00
Compare commits
8 commits
d398dec353
...
600bc5fd1a
| Author | SHA1 | Date | |
|---|---|---|---|
|
600bc5fd1a | ||
|
|
2f6867348f | ||
|
|
6b5ff04d00 | ||
|
|
ce5ae4d371 | ||
|
|
27315feb17 | ||
|
|
a1c930d0d1 | ||
|
|
9e959f3922 | ||
|
|
7c39427d8b |
|
|
@ -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 @@
|
|||
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 @@
|
|||
Swapped icon for X (fka. twitter) to updated logo in footer.
|
||||
|
|
@ -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
changelogs/internal/newsfragments/2282.clarification
Normal file
1
changelogs/internal/newsfragments/2282.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Replace the Twitter link in the footer with our BlueSky and Mastodon socials.
|
||||
|
|
@ -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
|
||||
|
|
@ -106,25 +106,30 @@ sidebar_menu_compact = true
|
|||
# desc = "Matrix on GitHub"
|
||||
# Custom links shown in the center of the footer. (Only supported by our fork of docsy's 'footer/central' partial.)
|
||||
[[params.links.bottom]]
|
||||
name = "GitHub"
|
||||
url = "https://github.com/matrix-org"
|
||||
icon = "fab fa-github"
|
||||
name = "GitHub"
|
||||
url = "https://github.com/matrix-org"
|
||||
icon = "fab fa-github"
|
||||
desc = "Matrix on GitHub"
|
||||
[[params.links.bottom]]
|
||||
name = "GitLab"
|
||||
url = "https://gitlab.matrix.org/matrix-org"
|
||||
icon = "fab fa-gitlab"
|
||||
name = "GitLab"
|
||||
url = "https://gitlab.matrix.org/matrix-org"
|
||||
icon = "fab fa-gitlab"
|
||||
desc = "Matrix on GitLab"
|
||||
[[params.links.bottom]]
|
||||
name = "YouTube"
|
||||
url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
|
||||
icon = "fab fa-youtube"
|
||||
name = "YouTube"
|
||||
url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
|
||||
icon = "fab fa-youtube"
|
||||
desc = "Matrix YouTube channel"
|
||||
[[params.links.bottom]]
|
||||
name = "Twitter"
|
||||
url = "https://twitter.com/matrixdotorg"
|
||||
icon = "fab fa-x-twitter"
|
||||
desc = "Matrix on Twitter"
|
||||
name = "Mastodon"
|
||||
url = "https://mastodon.matrix.org/@matrix"
|
||||
icon = "fab fa-mastodon"
|
||||
desc = "Matrix on Mastodon"
|
||||
[[params.links.bottom]]
|
||||
name = "Bluesky"
|
||||
url = "https://bsky.app/profile/matrix.org"
|
||||
icon = "fab fa-bluesky"
|
||||
desc = "Matrix on Bluesky"
|
||||
|
||||
|
||||
# configuration for the hugo development server
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -428,6 +426,8 @@ imports and similar behaviour).
|
|||
|
||||
#### Server admin style permissions
|
||||
|
||||
{{% changed-in v="1.17" %}}
|
||||
|
||||
The homeserver needs to give the application service *full control* over
|
||||
its namespace, both for users and for room aliases. This means that the
|
||||
AS should be able to manage any users and room alias in its namespace. No additional API
|
||||
|
|
@ -444,33 +444,59 @@ achieved by including the `as_token` on a `/register` request, along
|
|||
with a login type of `m.login.application_service` to set the desired
|
||||
user ID without a password.
|
||||
|
||||
POST /_matrix/client/v3/register
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
```http
|
||||
POST /_matrix/client/v3/register
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
```
|
||||
|
||||
Content:
|
||||
{
|
||||
"type": "m.login.application_service",
|
||||
"username": "_irc_example"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"type": "m.login.application_service",
|
||||
"username": "_irc_example"
|
||||
}
|
||||
```
|
||||
|
||||
Similarly, logging in as users needs API changes in order to allow the AS to
|
||||
log in without needing the user's password. This is achieved by including the
|
||||
`as_token` on a `/login` request, along with a login type of
|
||||
`m.login.application_service`:
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
Servers MUST still allow application services to use the `/register` endpoint
|
||||
with a login type of `m.login.application_service` even if they don't support
|
||||
the [Legacy Authentication API](/client-server-api/#legacy-api).
|
||||
|
||||
In that case application services MUST set the `"inhibit_login": true` parameter
|
||||
as they cannot use it to log in as users. If the `inhibit_login` parameter is
|
||||
not set to `true`, the server MUST return a 400 HTTP status code with an
|
||||
`M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Similarly, logging in as users using the [Legacy authentication API](/client-server-api/#legacy-api)
|
||||
needs API changes in order to allow the AS to log in without needing the user's
|
||||
password. This is achieved by including the `as_token` on a `/login` request,
|
||||
along with a login type of `m.login.application_service`:
|
||||
|
||||
{{% added-in v="1.2" %}}
|
||||
|
||||
POST /_matrix/client/v3/login
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
```http
|
||||
POST /_matrix/client/v3/login
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
```
|
||||
|
||||
Content:
|
||||
{
|
||||
"type": "m.login.application_service",
|
||||
"identifier": {
|
||||
"type": "m.id.user",
|
||||
"user": "_irc_example"
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"type": "m.login.application_service",
|
||||
"identifier": {
|
||||
"type": "m.id.user",
|
||||
"user": "_irc_example"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
Application services MUST NOT use the `/login` endpoint if the server doesn't
|
||||
support the Legacy authentication API. If `/login` is called with the
|
||||
`m.login.application_service` login type the server MUST return a 400 HTTP
|
||||
status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Application services which attempt to create users or aliases *outside*
|
||||
of their defined namespaces, or log in as users outside of their defined
|
||||
|
|
@ -512,6 +538,38 @@ client-server endpoint.
|
|||
|
||||
{{% http-api spec="client-server" api="appservice_room_directory" %}}
|
||||
|
||||
#### Device management
|
||||
|
||||
{{% added-in v="1.17" %}}
|
||||
|
||||
Application services need to be able to create and delete devices to manage the
|
||||
encryption for their users without having to rely on `/login`, which also
|
||||
generates an access token for the user, and which might not be available for
|
||||
homeservers that only support the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
|
||||
##### Creating devices
|
||||
|
||||
Application services can use the [`PUT /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#put_matrixclientv3devicesdeviceid)
|
||||
endpoint to create new devices.
|
||||
|
||||
##### Deleting devices
|
||||
|
||||
The following endpoints used to delete devices MUST NOT require [User-Interactive
|
||||
Authentication](/client-server-api/#user-interactive-authentication-api) when
|
||||
used by an application service:
|
||||
|
||||
* [`DELETE /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#delete_matrixclientv3devicesdeviceid)
|
||||
* [`POST /_matrix/client/v3/delete_devices`](/client-server-api/#post_matrixclientv3delete_devices)
|
||||
|
||||
#### Cross-signing
|
||||
|
||||
{{% added-in v="1.17" %}}
|
||||
|
||||
Appservices need to be able to verify themselves and replace their cross-signing
|
||||
keys, so the [`POST /_matrix/client/v3/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload)
|
||||
endpoint MUST NOT require [User-Interactive Authentication](/client-server-api/#user-interactive-authentication-api)
|
||||
when used by an application service, even if cross-signing keys already exist.
|
||||
|
||||
### Referencing messages from a third-party network
|
||||
|
||||
Application services should include an `external_url` in the `content`
|
||||
|
|
|
|||
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 %}}
|
||||
|
|
@ -477,8 +477,7 @@ the API that was used to obtain their current access token.
|
|||
|
||||
{{% boxes/note %}}
|
||||
Currently the OAuth 2.0 API doesn't cover all the use cases of the legacy API,
|
||||
such as automated applications that cannot use a web browser, or
|
||||
user management by [application services](application-service-api/#server-admin-style-permissions).
|
||||
such as automated applications that cannot use a web browser.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
### Authentication API discovery
|
||||
|
|
@ -502,6 +501,12 @@ user must do that directly in the homeserver's web UI. However, the client can
|
|||
signal to the homeserver that the user wishes to create a new account with the
|
||||
[`prompt=create`](#user-registration) parameter during authorization.
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
Application services can use the `/register` endpoint to create users regardless
|
||||
of the authentication API supported by the homeserver.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
### Login
|
||||
|
||||
With the legacy API, a client can obtain an access token by using one of the
|
||||
|
|
@ -1562,6 +1567,10 @@ If the access token does correspond to an appservice, but the user id does
|
|||
not lie within its namespace then the homeserver will respond with an
|
||||
errcode of `M_EXCLUSIVE`.
|
||||
|
||||
{{% added-in v="1.17" %}} If this login type is used and the server doesn't
|
||||
support logging in via the Legacy authentication API, it MUST return a 400 HTTP
|
||||
status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
|
||||
|
||||
##### Login Fallback
|
||||
|
||||
If a client does not recognize any or all login flows it can use the
|
||||
|
|
@ -4003,42 +4012,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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -21,13 +21,17 @@ paths:
|
|||
x-addedInMatrixVersion: "1.1"
|
||||
x-changedInMatrixVersion:
|
||||
"1.11": UIA is not always required for this endpoint.
|
||||
"1.17": |-
|
||||
This endpoint no longer requires User-Interactive Authentication when used by an
|
||||
application service.
|
||||
summary: Upload cross-signing keys.
|
||||
description: |-
|
||||
Publishes cross-signing keys for the user.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
|
||||
except when used by an application service.
|
||||
|
||||
User-Interactive Authentication MUST be performed, except in these cases:
|
||||
User-Interactive Authentication MUST be performed for regular clients, except in these cases:
|
||||
- there is no existing cross-signing master key uploaded to the homeserver, OR
|
||||
- there is an existing cross-signing master key and it exactly matches the
|
||||
cross-signing master key provided in the request body. If there are any additional
|
||||
|
|
|
|||
|
|
@ -87,8 +87,21 @@ paths:
|
|||
tags:
|
||||
- Device management
|
||||
put:
|
||||
summary: Update a device
|
||||
description: Updates the metadata on the given device.
|
||||
summary: Create or update a device
|
||||
x-changedInMatrixVersion:
|
||||
"1.17": The ability to create new devices was added.
|
||||
description: |-
|
||||
Updates the metadata on the given device, or creates a new device.
|
||||
|
||||
The ability to create new devices is only available to application
|
||||
services: regular clients may only update existing devices.
|
||||
|
||||
When a new device was created, the homeserver MUST return a 201 HTTP
|
||||
status code. It MUST return a 200 HTTP status code if a device was
|
||||
updated.
|
||||
|
||||
This endpoint is rate-limited for device creation. Servers MAY use login
|
||||
rate limits.
|
||||
operationId: updateDevice
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -127,19 +140,34 @@ paths:
|
|||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"201":
|
||||
description: |-
|
||||
The device was successfully created by the application service.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"404":
|
||||
description: The current user has no device with the given ID.
|
||||
tags:
|
||||
- Device management
|
||||
delete:
|
||||
summary: Delete a device
|
||||
x-changedInMatrixVersion:
|
||||
"1.17": |-
|
||||
This endpoint no longer requires User-Interactive Authentication when used by an
|
||||
application service.
|
||||
description: |-
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
|
||||
except when used by an application service.
|
||||
|
||||
Deletes the given device, and invalidates any access token associated with it.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
{{% /boxes/warning %}}
|
||||
operationId: deleteDevice
|
||||
|
|
@ -190,13 +218,18 @@ paths:
|
|||
/delete_devices:
|
||||
post:
|
||||
summary: Bulk deletion of devices
|
||||
x-changedInMatrixVersion:
|
||||
"1.17": |-
|
||||
This endpoint no longer requires User-Interactive Authentication when used by an
|
||||
application service.
|
||||
description: |-
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
|
||||
except when used by an application service.
|
||||
|
||||
Deletes the given devices, and invalidates any access token associated with them.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
{{% /boxes/warning %}}
|
||||
operationId: deleteDevices
|
||||
|
|
|
|||
|
|
@ -243,8 +243,13 @@ paths:
|
|||
}
|
||||
}
|
||||
"400":
|
||||
description: Part of the request was invalid. For example, the login type may
|
||||
not be recognised.
|
||||
description: |-
|
||||
Part of the request was invalid. For example, the login type may not be recognised.
|
||||
|
||||
Specific error codes used with this status code include:
|
||||
* {{% added-in v="1.17" %}} `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service
|
||||
used the `m.login.application_service` type, but the server doesn't support logging
|
||||
in via the Legacy authentication API.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -60,6 +60,18 @@ paths:
|
|||
|
||||
Any user ID returned by this API must conform to the grammar given in the
|
||||
[Matrix specification](/appendices/#user-identifiers).
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
Even if the server doesn't support the Legacy authentication API, it
|
||||
MUST support this endpoint for application services to be able to
|
||||
[create users](/application-service-api/#server-admin-style-permissions).
|
||||
|
||||
In that case application services MUST set the `"inhibit_login": true`
|
||||
parameter as they cannot use it to log in as users. If the
|
||||
`inhibit_login` parameter is not set to `true`, the server MUST return a
|
||||
400 HTTP status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
|
||||
{{% /boxes/note %}}
|
||||
operationId: register
|
||||
parameters:
|
||||
- in: query
|
||||
|
|
@ -203,6 +215,9 @@ paths:
|
|||
* `M_INVALID_USERNAME` : The desired user ID is not a valid user name.
|
||||
* `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace
|
||||
claimed by an application service.
|
||||
* {{% added-in v="1.17" %}} `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service
|
||||
used the `m.login.application_service` type without setting `inhibit_login` to `true`,
|
||||
but the server doesn't support logging in via the Legacy authentication API.
|
||||
|
||||
These errors may be returned at any stage of the registration process,
|
||||
including after authentication if the requested user ID was registered
|
||||
|
|
|
|||
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