wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Fixes #1182
This commit is contained in:
Richard van der Hoff 2022-07-28 13:45:54 +01:00 • committed by GitHub
parent 119197e798
commit b232148821
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 84 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

37
content/client-server-api/_index.md
View file

@ -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