diff --git a/changelogs/client_server/newsfragments/1185.clarification b/changelogs/client_server/newsfragments/1185.clarification new file mode 100644 index 00000000..0865507a --- /dev/null +++ b/changelogs/client_server/newsfragments/1185.clarification @@ -0,0 +1 @@ +Update "API Standards" section to clarify how JSON is used. diff --git a/changelogs/identity_service/newsfragments/1185.clarification b/changelogs/identity_service/newsfragments/1185.clarification new file mode 100644 index 00000000..0865507a --- /dev/null +++ b/changelogs/identity_service/newsfragments/1185.clarification @@ -0,0 +1 @@ +Update "API Standards" section to clarify how JSON is used. diff --git a/changelogs/server_server/newsfragments/1185.clarification b/changelogs/server_server/newsfragments/1185.clarification new file mode 100644 index 00000000..0865507a --- /dev/null +++ b/changelogs/server_server/newsfragments/1185.clarification @@ -0,0 +1 @@ +Update "API Standards" section to clarify how JSON is used. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index ca2b3d97..f391aeb1 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -13,20 +13,33 @@ clients which maintain a full local persistent copy of server state. ## API Standards The mandatory baseline for client-server communication in Matrix is -exchanging JSON objects over HTTP APIs. HTTPS is recommended for -communication, although HTTP may be supported as a fallback to support -basic HTTP clients. More efficient optional transports will in future be -supported as optional extensions - e.g. a packed binary encoding over -stream-cipher encrypted TCP socket for low-bandwidth/low-roundtrip -mobile usage. For the default HTTP transport, all API calls use a -Content-Type of `application/json`. In addition, all strings MUST be -encoded as UTF-8. +exchanging JSON objects over HTTP APIs. More efficient transports may be +specified in future as optional extensions. + +HTTPS is recommended for communication. The use of plain HTTP is not +recommended outside test environments. Clients are authenticated using opaque `access_token` strings (see [Client Authentication](#client-authentication) for details). +All `POST` and `PUT` endpoints, with the exception of +[`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload), require the +client to supply a request body containing a (potentially empty) JSON object. +Clients should supply a `Content-Type` header of `application/json` for all requests with JSON bodies, +but this is not required. + +Similarly, all endpoints require the server to return a JSON object, +with the exception of 200 responses to +[`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid) +and [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](#get_matrixmediav3thumbnailservernamemediaid). +Servers msut include a `Content-Type` header of `application/json` for all JSON responses. + +All JSON data, in requests or responses, must be encoded using UTF-8. + See also [Conventions for Matrix APIs](/appendices#conventions-for-matrix-apis) -in the Appendices for conventions which all Matrix APIs are expected to follow. +in the Appendices for conventions which all Matrix APIs are expected to follow, +and [Web Browser Clients](#web-browser-clients) below for additional +requirements for server responses. ### Standard error response @@ -196,6 +209,8 @@ only read state (e.g.: `/sync`, get account data, etc). The user is unable to reject an invite to join the server notices room. See the [Server Notices](#server-notices) module for more information. +### Transaction identifiers + The client-server API typically uses `HTTP PUT` to submit requests with a client-generated transaction identifier. This means that these requests are idempotent. The scope of a transaction identifier is a @@ -208,8 +223,6 @@ Some API endpoints may allow or require the use of `POST` requests without a transaction ID. Where this is optional, the use of a `PUT` request is strongly recommended. -{{% http-api spec="client-server" api="versions" %}} - ## Web Browser Clients It is realistic to expect that some clients will be written to be run @@ -308,6 +321,8 @@ specify parameter values. The flow for this method is as follows: {{% http-api spec="client-server" api="wellknown" %}} +{{% http-api spec="client-server" api="versions" %}} + ## Client Authentication Most API endpoints require the user to identify themselves by presenting diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 65369b3e..c4d4a31a 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -38,8 +38,21 @@ Appendix. The mandatory baseline for identity server communication in Matrix is exchanging JSON objects over HTTP APIs. HTTPS is required for -communication, and all API calls use a Content-Type of -`application/json`. In addition, strings MUST be encoded as UTF-8. +communication. + +All `POST` and `PUT` endpoints, with the exception (for historical reasons) of [`POST +/_matrix/identity/v2/account/logout`](#post_matrixidentityv2accountlogout), +require the client to supply a request body containing a (potentially empty) +JSON object. Clients should supply a `Content-Type` header of `application/json` +for all requests with JSON bodies, but this is not required. + +Similarly, all endpoints require the server to return a JSON object. Servers +must include a `Content-Type` header of `application/json` for all JSON +responses. + +All JSON data, in requests or responses, must be encoded using UTF-8. + +### Standard error response Any errors which occur at the Matrix API level MUST return a "standard error response". This is a JSON object which looks like: @@ -103,8 +116,6 @@ the third party identifier. `M_UNKNOWN` An unknown error has occurred. -{{% http-api spec="identity" api="versions" %}} - ## Privacy Identity is a privacy-sensitive issue. While the identity server exists @@ -131,6 +142,10 @@ recommended CORS headers to be returned by servers on all requests are: Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization +## API Version check + +{{% http-api spec="identity" api="versions" %}} + ## Authentication Most endpoints in the Identity Service API require authentication diff --git a/content/server-server-api.md b/content/server-server-api.md index 12d4bc45..2a034c35 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -47,13 +47,42 @@ an HTTPS PUT request. ## API standards -The mandatory baseline for client-server communication in Matrix is -exchanging JSON objects over HTTP APIs. More efficient optional -transports will in future be supported as optional extensions - e.g. a -packed binary encoding over stream-cipher encrypted TCP socket for -low-bandwidth/low-roundtrip mobile usage. For the default HTTP -transport, all API calls use a Content-Type of `application/json`. In -addition, all strings MUST be encoded as UTF-8. +The mandatory baseline for server-server communication in Matrix is +exchanging JSON objects over HTTPS APIs. More efficient transports may be +specified in future as optional extensions. + +All `POST` and `PUT` endpoints require the requesting server to supply a +request body containing a (potentially empty) JSON object. Requesting servers +should supply a `Content-Type` header of `application/json` for all requests +with JSON bodies, but this is not required. + +Similarly, all endpoints in this specification require the destination server +to return a JSON object. Servers must include a `Content-Type` header of +`application/json` for all JSON responses. + +All JSON data, in requests or responses, must be encoded using UTF-8. + +### TLS + +Server-server communication must take place over HTTPS. + +The destination server must provide a TLS certificate signed by a known +Certificate Authority. + +Requesting servers are ultimately responsible for determining the trusted Certificate +Authorities, however are strongly encouraged to rely on the operating system's +judgement. Servers can offer administrators a means to override the trusted +authorities list. Servers can additionally skip the certificate validation for +a given whitelist of domains or netmasks for the purposes of testing or in +networks where verification is done elsewhere, such as with `.onion` +addresses. + +Servers should respect SNI when making requests where possible: a SNI should be +sent for the certificate which is expected, unless that certificate is expected +to be an IP address in which case SNI is not supported and should not be sent. + +Servers are encouraged to make use of the [Certificate +Transparency](https://www.certificate-transparency.org/) project. ## Server discovery @@ -143,22 +172,6 @@ delegation are: and other applications using SRV records such [XMPP](https://datatracker.ietf.org/doc/html/rfc6120#section-13.7.2.1). {{% /boxes/note %}} -The TLS certificate provided by the target server must be signed by a -known Certificate Authority. Servers are ultimately responsible for -determining the trusted Certificate Authorities, however are strongly -encouraged to rely on the operating system's judgement. Servers can -offer administrators a means to override the trusted authorities list. -Servers can additionally skip the certificate validation for a given -whitelist of domains or netmasks for the purposes of testing or in -networks where verification is done elsewhere, such as with `.onion` -addresses. Servers should respect SNI when making requests where -possible: a SNI should be sent for the certificate which is expected, -unless that certificate is expected to be an IP address in which case -SNI is not supported and should not be sent. - -Servers are encouraged to make use of the [Certificate -Transparency](https://www.certificate-transparency.org/) project. - {{% http-api spec="server-server" api="wellknown" %}} ### Server implementation