Version all appservice endpoints and provide a fallback

Fixes https://github.com/matrix-org/matrix-doc/issues/1616
pull/1629/head
Travis Ralston 6 years ago
parent ab14f33060
commit be5c566028

@ -19,13 +19,13 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: "/" basePath: /_matrix/app/v1
consumes: consumes:
- application/json - application/json
produces: produces:
- application/json - application/json
paths: paths:
"/_matrix/app/unstable/thirdparty/protocol/{protocol}": "/thirdparty/protocol/{protocol}":
get: get:
summary: Retrieve metadata about a specific protocol that the application service supports. summary: Retrieve metadata about a specific protocol that the application service supports.
description: |- description: |-
@ -72,7 +72,7 @@ paths:
} }
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user/{protocol}": "/thirdparty/user/{protocol}":
get: get:
summary: Retrieve the Matrix User ID of a corresponding third party user. summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |- description: |-
@ -125,7 +125,7 @@ paths:
} }
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location/{protocol}": "/thirdparty/location/{protocol}":
get: get:
summary: Retrieve Matrix-side portal rooms leading to a third party location. summary: Retrieve Matrix-side portal rooms leading to a third party location.
description: |- description: |-
@ -176,7 +176,7 @@ paths:
} }
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location": "/thirdparty/location":
get: get:
summary: Reverse-lookup third party locations given a Matrix room alias. summary: Reverse-lookup third party locations given a Matrix room alias.
description: |- description: |-
@ -221,7 +221,7 @@ paths:
} }
schema: schema:
$ref: ../client-server/definitions/errors/error.yaml $ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user": "/thirdparty/user":
get: get:
summary: Reverse-lookup third party users given a Matrix User ID. summary: Reverse-lookup third party users given a Matrix User ID.
description: |- description: |-

@ -20,7 +20,7 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: "/" basePath: /_matrix/app/v1
consumes: consumes:
- application/json - application/json
produces: produces:

@ -20,7 +20,7 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: "/" basePath: /_matrix/app/v1
consumes: consumes:
- application/json - application/json
produces: produces:

@ -20,7 +20,7 @@ host: localhost:8008
schemes: schemes:
- https - https
- http - http
basePath: "/" basePath: /_matrix/app/v1
produces: produces:
- application/json - application/json
paths: paths:

@ -169,6 +169,34 @@ An example registration file for an IRC-bridging application service is below:
Homeserver -> Application Service API Homeserver -> Application Service API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Legacy routes
+++++++++++++
Previous drafts of the application service specification had a mix of endpoints
that have been used in the wild for a significant amount of time. The application
service specification now defines a version on all endpoints to be more compatible
with the rest of the Matrix specification and the future.
Homeservers should attempt to use the specified endpoints first when communicating
with application services. However, if the application service receives an http status
code that does not indicate success (ie: 404, 500, 501, etc) then the homeserver
should fall back to the older endpoints for the application service.
The older endpoints have the exact same request body and response format, they
just belong at a different path. The equivalent path for each is as follows:
* ``/_matrix/app/v1/transactions/{txnId}`` becomes ``/transactions/{txnId}``
* ``/_matrix/app/v1/users/{userId}`` becomes ``/users/{userId}``
* ``/_matrix/app/v1/rooms/{roomAlias}`` becomes ``/rooms/{roomAlias}``
* ``/_matrix/app/v1/thirdparty/protocol/{protocol}`` becomes ``/_matrix/app/unstable/thirdparty/protocol/{protocol}``
* ``/_matrix/app/v1/thirdparty/user/{user}`` becomes ``/_matrix/app/unstable/thirdparty/user/{user}``
* ``/_matrix/app/v1/thirdparty/location/{location}`` becomes ``/_matrix/app/unstable/thirdparty/location/{location}``
* ``/_matrix/app/v1/thirdparty/user`` becomes ``/_matrix/app/unstable/thirdparty/user``
* ``/_matrix/app/v1/thirdparty/location`` becomes ``/_matrix/app/unstable/thirdparty/location``
Homeservers should periodically try again for the newer endpoints because the
application service may have been updated.
Pushing events Pushing events
++++++++++++++ ++++++++++++++

Loading…
Cancel
Save