From f308b7543c8d6e8893eed33f1bb120ced58e85b2 Mon Sep 17 00:00:00 2001
From: Daniel Wagner-Hall <daniel@matrix.org>
Date: Thu, 3 Dec 2015 16:26:45 +0000
Subject: [PATCH] Specify /admin/whois/{userId}

---
 api/client-server/admin.yaml       | 103 +++++++++++++++++++++++++++++
 specification/feature_profiles.rst |   2 +
 specification/modules/admin.rst    |  12 ++++
 specification/targets.yaml         |   1 +
 4 files changed, 118 insertions(+)
 create mode 100644 api/client-server/admin.yaml
 create mode 100644 specification/modules/admin.rst

diff --git a/api/client-server/admin.yaml b/api/client-server/admin.yaml
new file mode 100644
index 00000000..06926b3a
--- /dev/null
+++ b/api/client-server/admin.yaml
@@ -0,0 +1,103 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Administration API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%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:
+  "/admin/whois/{userId}":
+    get:
+      summary: Gets information about a particular user.
+      description: |-
+        Gets information about a particular user.
+
+        This API may be restricted to only be called by the user being looked
+        up, or by a server admin. Server-local administrator privileges are not
+        specified in this document.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user to look up.
+          required: true
+          x-example: "@peter:rabbit.rocks"
+      responses:
+        200:
+          description: The lookup was successful.
+          examples:
+            application/json: |-
+              {
+                "user_id": "@peter:rabbit.rocks",
+                "devices": {
+                  "teapot": {
+                    "sessions": [
+                      {
+                        "connections": [
+                          {
+                            "ip": "127.0.0.1",
+                            "last_seen": 1411996332123,
+                            "user_agent": "curl/7.31.0-DEV"
+                          },
+                          {
+                            "ip": "10.0.0.2",
+                            "last_seen": 1411996332123,
+                            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The Matrix user ID of the user.
+              devices:
+                type: object
+                description: |-
+                  Each key is an identitfier for one of the user's devices.
+                additionalProperties:
+                  type: object
+                  title: DeviceInfo
+                  properties:
+                    sessions:
+                      type: array
+                      description: A user's sessions (i.e. what they did with an access token from one login).
+                      items:
+                        type: object
+                        title: SessionInfo
+                        properties:
+                          connections:
+                            type: array
+                            description: Information particular connections in the session.
+                            items:
+                              type: object
+                              title: ConnectionInfo
+                              properties:
+                                ip:
+                                  type: string
+                                  description: Most recently seen IP address of the session.
+                                last_seen:
+                                  type: number
+                                  description: Unix timestamp that the session was last active.
+                                user_agent:
+                                  type: string
+                                  description: User agent string last seen in the session.
diff --git a/specification/feature_profiles.rst b/specification/feature_profiles.rst
index 49927279..a5d19a61 100644
--- a/specification/feature_profiles.rst
+++ b/specification/feature_profiles.rst
@@ -26,6 +26,7 @@ Summary
  `Content Repository`_                 Required   Required   Required   Optional   Optional
  `Managing History Visibility`_        Required   Required   Required   Required   Optional
  `Server Side Search`_                 Optional   Optional   Optional   Optional   Optional
+ `Server Administration`_              Optional   Optional   Optional   Optional   Optional
 ===================================== ========== ========== ========== ========== ==========
 
 *Please see each module for more details on what clients need to implement.*
@@ -39,6 +40,7 @@ Summary
 .. _Content Repository: `module:content`_
 .. _Managing History Visibility: `module:history-visibility`_
 .. _Server Side Search: `module:search`_
+.. _Server Administration: `module:admin`_
 
 Clients
 -------
diff --git a/specification/modules/admin.rst b/specification/modules/admin.rst
new file mode 100644
index 00000000..45d1064f
--- /dev/null
+++ b/specification/modules/admin.rst
@@ -0,0 +1,12 @@
+Server Administration
+=====================
+
+.. _module:admin:
+
+This module adds capabilities for server administrators to inspect server state
+and data.
+
+Client Behaviour
+----------------
+
+{{admin_http_api}}
diff --git a/specification/targets.yaml b/specification/targets.yaml
index 310870a0..45a9121b 100644
--- a/specification/targets.yaml
+++ b/specification/targets.yaml
@@ -35,6 +35,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/guest_access.rst
     - modules/tags.rst
     - modules/account_data.rst
+    - modules/admin.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@"]