From e072d215cf466e76552a6eb53dc9e1cea8a4838c Mon Sep 17 00:00:00 2001
From: Daniel Wagner-Hall <daniel@matrix.org>
Date: Wed, 2 Dec 2015 15:27:25 +0000
Subject: [PATCH] Specify redaction

---
 api/client-server/redaction.yaml    | 82 +++++++++++++++++++++++++++++
 specification/client_server_api.rst | 17 +++---
 2 files changed, 92 insertions(+), 7 deletions(-)
 create mode 100644 api/client-server/redaction.yaml

diff --git a/api/client-server/redaction.yaml b/api/client-server/redaction.yaml
new file mode 100644
index 000000000..d30ef8c16
--- /dev/null
+++ b/api/client-server/redaction.yaml
@@ -0,0 +1,82 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server message redaction API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/redact/{eventId}/{txnId}":
+    put:
+      summary: Strips all non-integrity-critical information out of an event.
+      description: |-
+        Strips all information out of an event which isn't critical to the
+        integrity of the server-side representation of the room.
+
+        This cannot be undone.
+
+        Users may redact their own events, and any user with a power level
+        greater than or equal to the `redact` power level of the room may
+        redact events there.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room from which to redact the event.
+          required: true
+          x-example: "!637q39766251:example.com"
+        - in: path
+          type: string
+          name: eventId
+          description: The ID of the event to redact
+          required: true
+          x-example: "bai2b1i9:matrix.org"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate a
+            unique ID; it will be used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "37"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "reason": "Indecent material"
+              }
+            properties:
+              reason:
+                type: string
+                description: The reason for the event being redacted.
+      responses:
+        200:
+          description: "An ID for the redaction event."
+          examples:
+            application/json: |-
+              {
+                  "event_id": "YUwQidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst
index 67973c6b3..4c24c3503 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -793,10 +793,6 @@ owners to delete the offending content from the databases. Events that have been
 redacted include a ``redacted_because`` key whose value is the event that caused
 it to be redacted, which may include a reason.
 
-.. TODO
-  Currently, only room admins can redact events by sending a ``m.room.redaction``
-  event, but server admins also need to be able to redact events by a similar
-  mechanism.
 
 Upon receipt of a redaction event, the server should strip off any keys not in
 the following list:
@@ -819,13 +815,20 @@ one of the following event types:
    ``kick``, ``redact``, ``state_default``, ``users``, ``users_default``.
 - ``m.room.aliases`` allows key ``aliases``
 
-.. TODO
-  Need to update m.room.power_levels to reflect new power levels formatting
-
 The redaction event should be added under the key ``redacted_because``. When a
 client receives a redaction event it should change the redacted event
 in the same way a server does.
 
+Events
+++++++
+
+{{m_room_redaction_event}}
+
+Client behaviour
+++++++++++++++++
+
+{{redaction_http_api}}
+
 Rooms
 -----