Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify the use of JSON in requests and responses #1185

Merged
merged 4 commits into from
Jul 28, 2022
Merged

Clarify the use of JSON in requests and responses #1185

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
612cd0a
Clarify the use of JSON in requests and responses
richvdh Jul 26, 2022
5ee403a
Update content/identity-service-api.md
richvdh Jul 27, 2022
15726ed
Update content/client-server-api/_index.md
richvdh Jul 28, 2022
2320b91
Apply suggestions from code review
richvdh Jul 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/1185.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Update "API Standards" section to clarify how JSON is used.
1 change: 1 addition & 0 deletions changelogs/identity_service/newsfragments/1185.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Update "API Standards" section to clarify how JSON is used.
1 change: 1 addition & 0 deletions changelogs/server_server/newsfragments/1185.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Update "API Standards" section to clarify how JSON is used.
37 changes: 26 additions & 11 deletions content/client-server-api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/msut/must/

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bother. thanks.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed in 3dc3150


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

Expand Down Expand Up @@ -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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gave this a new heading to stop it being stuck under "Other error codes"


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
Expand All @@ -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" %}}
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and moved this into "discovery" (for want of a better place), for the same reason.


## Web Browser Clients

It is realistic to expect that some clients will be written to be run
Expand Down Expand Up @@ -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
Expand Down
23 changes: 19 additions & 4 deletions content/identity-service-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
59 changes: 36 additions & 23 deletions content/server-server-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down