From 6bcb1798f5bf8b0a395022cf62ac89fa4c13d0a0 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Tue, 12 Jul 2016 16:18:48 +0100
Subject: [PATCH] Mark deprecated endpoints with their replacements

Fixes https://matrix.org/jira/browse/SPEC-415
---
 api/client-server/old_sync.yaml     | 13 +++++++++++++
 api/client-server/rooms.yaml        |  5 +++++
 specification/client_server_api.rst |  3 +++
 3 files changed, 21 insertions(+)

diff --git a/api/client-server/old_sync.yaml b/api/client-server/old_sync.yaml
index b689b775..aa2577cc 100644
--- a/api/client-server/old_sync.yaml
+++ b/api/client-server/old_sync.yaml
@@ -20,6 +20,11 @@ paths:
       description: |-
         This will listen for new events and return them to the caller. This will
         block until an event is received, or until the ``timeout`` is reached.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        should instead call the |/sync|_ API with a ``since`` parameter. See
+        the `migration guide
+        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
       security:
         - accessToken: []
       parameters:
@@ -92,6 +97,11 @@ paths:
       description: |-
         This returns the full state for this user, with an optional limit on the
         number of messages per room to return.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        should instead call the |/sync|_ API with no ``since`` parameter. See
+        the `migration guide
+        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
       security:
         - accessToken: []
       parameters:
@@ -373,6 +383,9 @@ paths:
       description: |-
         Get a single event based on ``event_id``. You must have permission to
         retrieve this event e.g. by being a member in the room for this event.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        should instead call the |/rooms/{roomId}/context/{eventId}|_ API.
       security:
         - accessToken: []
       parameters:
diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml
index 6b9f28f2..e4b5b1de 100644
--- a/api/client-server/rooms.yaml
+++ b/api/client-server/rooms.yaml
@@ -222,6 +222,11 @@ paths:
       summary: Snapshot the current state of a room and its most recent messages.
       description: |-
         Get a copy of the current state and the most recent messages in a room.
+
+        This endpoint was deprecated in r0 of this specification. There is no
+        direct replacement; the relevant information is returned by the
+        |/sync|_ API. See the `migration guide
+        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
       security:
         - accessToken: []
       parameters:
diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst
index 17a86922..de869357 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -1174,5 +1174,8 @@ have to wait in milliseconds before they can try again.
 .. |/rooms/<room_id>/unban| replace:: ``/rooms/<room_id>/unban``
 .. _/rooms/<room_id>/unban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-unban
 
+.. |/rooms/{roomId}/context/{eventId}| replace:: ``/_matrix/client/unstable/rooms/{roomId}/context/{eventId}``
+.. _/rooms/{roomId}/context/{eventId}: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-context-eventid
+
 .. |/account/3pid| replace:: ``/account/3pid``
 .. _/account/3pid: #post-matrix-client-%CLIENT_MAJOR_VERSION%-account-3pid