Merge pull request #168 from matrix-org/markjh/client_config

Add API for setting client config

api/client-server/v1/sync.yaml

@@ -131,6 +131,14 @@ paths:
                           "type": "m.presence"
                       }
                   ],
+                  "account_data": [
+                    {
+                      "type": "org.example.custom.config",
+                      "content": {
+                        "custom_config_key": "custom_config_value"
+                      }
+                    }
+                  ],
                   "rooms": [
                       {
                           "membership": "join",
@@ -246,10 +254,18 @@ paths:
                               }
                           ],
                           "visibility": "private",
-                          "account_data": [{
+                          "account_data": [
+                            {
                               "type": "m.tag",
-                            "content": {"tags": {"work": {"order": "1"}}}
+                              "content": {"tags": {"work": {"order": 1}}}
-                          }]
+                            },
+                            {
+                              "type": "org.example.custom.room.config",
+                              "content": {
+                                "custom_config_key": "custom_config_value"
+                              }
+                            }
+                          ]
                       }
                   ]
               }

api/client-server/v2_alpha/account-data.yaml

@@ -0,0 +1,105 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Client Config API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/v2_alpha
+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:
+  "/user/{userId}/account_data/{type}":
+    put:
+      summary: Set some account_data for the user.
+      description: |-
+        Set some account_data for the client. This config is only visible to the user
+        that set the account_data. The config will be synced to clients in the
+        top-level ``account_data``.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The id of the user to set account_data for. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: type
+          required: true
+          description: |-
+            The event type of the account_data to set. Custom types should be
+            namespaced to avoid clashes.
+          x-example: "org.example.custom.config"
+        - in: body
+          name: content
+          required: true
+          description: |-
+            The content of the account_data
+          schema:
+            type: object
+            example: |-
+              {"custom_account_data_key": "custom_config_value"}
+      responses:
+        200:
+          description:
+            The account_data was successfully added.
+  "/user/{userId}/rooms/{roomId}/account_data/{type}":
+    put:
+      summary: Set some account_data for the user.
+      description: |-
+        Set some account_data for the client on a given room. This config is only
+        visible to the user that set the account_data. The config will be synced to
+        clients in the per-room ``account_data``.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The id of the user to set account_data for. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          required: true
+          description: |-
+            The id of the room to set account_data on.
+          x-example: "!726s6s6q:example.com"
+        - in: path
+          type: string
+          name: type
+          required: true
+          description: |-
+            The event type of the account_data to set. Custom types should be
+            namespaced to avoid clashes.
+          x-example: "org.example.custom.room.config"
+        - in: body
+          name: content
+          required: true
+          description: |-
+            The content of the account_data
+          schema:
+            type: object
+            example: |-
+              {"custom_account_data_key": "custom_account_data_value"}
+      responses:
+        200:
+          description:
+            The account_data was successfully added.

api/client-server/v2_alpha/sync.yaml

@@ -211,6 +211,16 @@ paths:
                     }
                   ]
                 },
+                "account_data": {
+                  "events": [
+                    {
+                      "type": "org.example.custom.config",
+                      "content": {
+                        "custom_config_key": "custom_config_value"
+                      }
+                    }
+                  ]
+                },
                 "rooms": {
                   "join": {
                     "!726s6s6q:example.com": {
@@ -265,7 +275,13 @@ paths:
                         "events": [
                           {
                             "type": "m.tag",
-                            "content": {"tags": {"work": {"order": "1"}}}
+                            "content": {"tags": {"work": {"order": 1}}}
+                          },
+                          {
+                            "type": "org.example.custom.room.config",
+                            "content": {
+                              "custom_config_key": "custom_config_value"
+                            }
                           }
                         ]
                       }

specification/modules/account_data.rst

@@ -0,0 +1,27 @@
+Client Config
+=============
+
+.. _module:account_data:
+
+Clients can store custom config data for their account on their homeserver.
+This account data will be synced between different devices and can persist
+across installations on a particular device. Users may only view the account
+data for their own account
+
+The account_data may be either global or scoped to a particular rooms.
+
+Events
+------
+
+The client recieves the account data as events in the ``account_data`` sections
+of a v2 /sync.
+
+These events can also be received in a v1 /events response or in the
+``account_data`` section of a room in v1 /initialSync. ``m.tag``
+events appearing in v1 /events will have a ``room_id`` with the room
+the tags are for.
+
+Client Behaviour
+----------------
+
+{{v2_account_data_http_api}}

specification/targets.yaml

@@ -27,6 +27,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/search.rst
     - modules/guest_access.rst
     - modules/tags.rst
+    - modules/account_data.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`"]