From eeb43043adc4ed34cd82282430d19669d389d8c4 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 22 Nov 2022 10:51:29 -0500 Subject: [PATCH] Add standard error responses (MSC3743). (#1347) --- .../application_service/newsfragments/1347.feature | 1 + changelogs/client_server/newsfragments/1347.feature | 1 + changelogs/identity_service/newsfragments/1347.feature | 1 + changelogs/push_gateway/newsfragments/1347.feature | 1 + changelogs/server_server/newsfragments/1347.feature | 1 + content/application-service-api.md | 8 ++++++++ content/client-server-api/_index.md | 8 +++++--- content/identity-service-api.md | 5 +++++ content/push-gateway-api.md | 10 ++++++++++ content/server-server-api.md | 8 ++++++++ 10 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 changelogs/application_service/newsfragments/1347.feature create mode 100644 changelogs/client_server/newsfragments/1347.feature create mode 100644 changelogs/identity_service/newsfragments/1347.feature create mode 100644 changelogs/push_gateway/newsfragments/1347.feature create mode 100644 changelogs/server_server/newsfragments/1347.feature diff --git a/changelogs/application_service/newsfragments/1347.feature b/changelogs/application_service/newsfragments/1347.feature new file mode 100644 index 00000000..175d13d5 --- /dev/null +++ b/changelogs/application_service/newsfragments/1347.feature @@ -0,0 +1 @@ +Add information on standard error responses for unknown endpoints/methods. diff --git a/changelogs/client_server/newsfragments/1347.feature b/changelogs/client_server/newsfragments/1347.feature new file mode 100644 index 00000000..175d13d5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1347.feature @@ -0,0 +1 @@ +Add information on standard error responses for unknown endpoints/methods. diff --git a/changelogs/identity_service/newsfragments/1347.feature b/changelogs/identity_service/newsfragments/1347.feature new file mode 100644 index 00000000..175d13d5 --- /dev/null +++ b/changelogs/identity_service/newsfragments/1347.feature @@ -0,0 +1 @@ +Add information on standard error responses for unknown endpoints/methods. diff --git a/changelogs/push_gateway/newsfragments/1347.feature b/changelogs/push_gateway/newsfragments/1347.feature new file mode 100644 index 00000000..175d13d5 --- /dev/null +++ b/changelogs/push_gateway/newsfragments/1347.feature @@ -0,0 +1 @@ +Add information on standard error responses for unknown endpoints/methods. diff --git a/changelogs/server_server/newsfragments/1347.feature b/changelogs/server_server/newsfragments/1347.feature new file mode 100644 index 00000000..175d13d5 --- /dev/null +++ b/changelogs/server_server/newsfragments/1347.feature @@ -0,0 +1 @@ +Add information on standard error responses for unknown endpoints/methods. diff --git a/content/application-service-api.md b/content/application-service-api.md index 2023af00..fa24d6fd 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -164,6 +164,14 @@ each is as follows: Homeservers should periodically try again for the newer endpoints because the application service may have been updated. +#### Unknown routes + +If a request for an unsupported (or unknown) endpoint is received then the server +must respond with a 404 `M_UNRECOGNIZED` error. + +Similarly, a 405 `M_UNRECOGNIZED` error is used to denote an unsupported method +to a known endpoint. + #### Pushing events The application service API provides a transaction API for sending a diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index e8255dfa..8c2c0322 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -107,6 +107,11 @@ No resource was found for this request. Too many requests have been sent in a short period of time. Wait a while then try again. +`M_UNRECOGNIZED` +The server did not understand the request. This is expected to be returned with +a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status +code if the endpoint is implemented, but the incorrect HTTP method is used. + `M_UNKNOWN` An unknown error has occurred. @@ -116,9 +121,6 @@ The following error codes are specific to certain endpoints. -`M_UNRECOGNIZED` -The server did not understand the request. - `M_UNAUTHORIZED` The request was not correctly authorized. Usually due to login failures. diff --git a/content/identity-service-api.md b/content/identity-service-api.md index eac159b7..a9676120 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -108,6 +108,11 @@ attempting to verify ownership of a given third party address. The request contained an unrecognised value, such as an unknown token or medium. +This is also used as the response if a server did not understand the request. +This is expected to be returned with a 404 HTTP status code if the endpoint is +not implemented or a 405 HTTP status code if the endpoint is implemented, but +the incorrect HTTP method is used. + `M_THREEPID_IN_USE` The third party identifier is already in use by another user. Typically this error will have an additional `mxid` property to indicate who owns diff --git a/content/push-gateway-api.md b/content/push-gateway-api.md index 541db129..5fb36d7c 100644 --- a/content/push-gateway-api.md +++ b/content/push-gateway-api.md @@ -37,6 +37,16 @@ notification provider (e.g. APNS, GCM). Mobile Device or Client ``` +## API standards + +### Unsupported endpoints + +If a request for an unsupported (or unknown) endpoint is received then the server +must respond with a 404 `M_UNRECOGNIZED` error. + +Similarly, a 405 `M_UNRECOGNIZED` error is used to denote an unsupported method +to a known endpoint. + ## Homeserver behaviour This describes the format used by "HTTP" pushers to send notifications diff --git a/content/server-server-api.md b/content/server-server-api.md index 7b33a956..1f325e27 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -84,6 +84,14 @@ 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. +### Unsupported endpoints + +If a request for an unsupported (or unknown) endpoint is received then the server +must respond with a 404 `M_UNRECOGNIZED` error. + +Similarly, a 405 `M_UNRECOGNIZED` error is used to denote an unsupported method +to a known endpoint. + ## Server discovery ### Resolving server names