Clarify the use of JSON in requests and responses (#1185)

Fixes #1182

changelogs/client_server/newsfragments/1185.clarification

@@ -0,0 +1 @@
+Update "API Standards" section to clarify how JSON is used.

changelogs/identity_service/newsfragments/1185.clarification

@@ -0,0 +1 @@
+Update "API Standards" section to clarify how JSON is used.

changelogs/server_server/newsfragments/1185.clarification

@@ -0,0 +1 @@
+Update "API Standards" section to clarify how JSON is used.

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
+exchanging JSON objects over HTTP APIs. More efficient transports may be
-communication, although HTTP may be supported as a fallback to support
+specified in future as optional extensions.
-basic HTTP clients. More efficient optional transports will in future be
+
-supported as optional extensions - e.g. a packed binary encoding over
+HTTPS is recommended for communication. The use of plain HTTP is not
-stream-cipher encrypted TCP socket for low-bandwidth/low-roundtrip
+recommended outside test environments.
-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.
 
 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

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
+communication.
-`application/json`. In addition, strings MUST be encoded as UTF-8.
+
+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

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
+The mandatory baseline for server-server communication in Matrix is
-exchanging JSON objects over HTTP APIs. More efficient optional
+exchanging JSON objects over HTTPS APIs. More efficient transports may be
-transports will in future be supported as optional extensions - e.g. a
+specified in future as optional extensions.
-packed binary encoding over stream-cipher encrypted TCP socket for
+
-low-bandwidth/low-roundtrip mobile usage. For the default HTTP
+All `POST` and `PUT` endpoints require the requesting server to supply a
-transport, all API calls use a Content-Type of `application/json`. In
+request body containing a (potentially empty) JSON object. Requesting servers
-addition, all strings MUST be encoded as UTF-8.
+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