From be5c5660282a74128047aa3ec98df1fcbffe0ca5 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Thu, 30 Aug 2018 11:03:42 -0600
Subject: [PATCH] Version all appservice endpoints and provide a fallback

Fixes https://github.com/matrix-org/matrix-doc/issues/1616
---
 api/application-service/protocols.yaml    | 12 +++++-----
 api/application-service/query_room.yaml   |  2 +-
 api/application-service/query_user.yaml   |  2 +-
 api/application-service/transactions.yaml |  2 +-
 specification/application_service_api.rst | 28 +++++++++++++++++++++++
 5 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/api/application-service/protocols.yaml b/api/application-service/protocols.yaml
index e6489cc5..f1dd39b0 100644
--- a/api/application-service/protocols.yaml
+++ b/api/application-service/protocols.yaml
@@ -19,13 +19,13 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: "/"
+basePath: /_matrix/app/v1
 consumes:
   - application/json
 produces:
   - application/json
 paths:
-  "/_matrix/app/unstable/thirdparty/protocol/{protocol}":
+  "/thirdparty/protocol/{protocol}":
     get:
       summary: Retrieve metadata about a specific protocol that the application service supports.
       description: |-
@@ -72,7 +72,7 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/user/{protocol}":
+  "/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third party user.
       description: |-
@@ -125,7 +125,7 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/location/{protocol}":
+  "/thirdparty/location/{protocol}":
     get:
       summary: Retrieve Matrix-side portal rooms leading to a third party location.
       description: |-
@@ -176,7 +176,7 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/location":
+  "/thirdparty/location":
     get:
       summary: Reverse-lookup third party locations given a Matrix room alias.
       description: |-
@@ -221,7 +221,7 @@ paths:
             }
           schema:
             $ref: ../client-server/definitions/errors/error.yaml
-  "/_matrix/app/unstable/thirdparty/user":
+  "/thirdparty/user":
     get:
       summary: Reverse-lookup third party users given a Matrix User ID.
       description: |-
diff --git a/api/application-service/query_room.yaml b/api/application-service/query_room.yaml
index b885cb86..22f15dcf 100644
--- a/api/application-service/query_room.yaml
+++ b/api/application-service/query_room.yaml
@@ -20,7 +20,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: "/"
+basePath: /_matrix/app/v1
 consumes:
   - application/json
 produces:
diff --git a/api/application-service/query_user.yaml b/api/application-service/query_user.yaml
index 0431b5e4..af7dec5c 100644
--- a/api/application-service/query_user.yaml
+++ b/api/application-service/query_user.yaml
@@ -20,7 +20,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: "/"
+basePath: /_matrix/app/v1
 consumes:
   - application/json
 produces:
diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml
index 8735cc8f..9bedc502 100644
--- a/api/application-service/transactions.yaml
+++ b/api/application-service/transactions.yaml
@@ -20,7 +20,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: "/"
+basePath: /_matrix/app/v1
 produces:
   - application/json
 paths:
diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst
index 5b7abf4a..3aa8a8ed 100644
--- a/specification/application_service_api.rst
+++ b/specification/application_service_api.rst
@@ -169,6 +169,34 @@ An example registration file for an IRC-bridging application service is below:
 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
 ++++++++++++++