Merge pull request #1152 from turt2live/travis/clarify-whoami

Improve documentation around /account/whoami

api/client-server/whoami.yaml

@@ -29,7 +29,14 @@ paths:
     get:
       summary: Gets information about the owner of an access token.
       description: |-
-        Gets information about the owner of a given access token.
+        Gets information about the owner of a given access token. 
+        
+        Note that, as with the rest of the Client-Server API, 
+        Application Services may masquerade as users within their 
+        namespace by giving a ``user_id`` query parameter. In this 
+        situation, the server should verify that the given ``user_id``
+        is registered by the appservice, and return it in the response 
+        body.
       operationId: getTokenOwner
       security:
         - accessToken: []
@@ -40,8 +47,8 @@ paths:
             The token belongs to a known user.
           examples:
             application/json: {
-                "user_id": "@joe:example.org"
-              }
+              "user_id": "@joe:example.org"
+            }
           schema:
             type: object
             required: ["user_id"]
@@ -49,5 +56,29 @@ paths:
               user_id:
                 type: string
                 description: The user id that owns the access token.
+        401:
+          description:
+            The token is not recognised
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN_TOKEN",
+              "error": "Unrecognised access token."
+            }
+          schema:
+            "$ref": "definitions/error.yaml"
+        403:
+          description:
+            The appservice cannot masquerade as the user or has not registered them.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "Application service has not registered this user."
+            }
+          schema:
+            "$ref": "definitions/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - User data