From 8a676a2b9d49fb38f00e1ae810fb7e698a1cfc49 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Mon, 1 Jun 2015 16:29:19 +0100
Subject: [PATCH] Add sortFn for profile HTTP API. Add combined profile HTTP
 API.

---
 api/client-server/v1/profile.yaml       | 45 ++++++++++++++++++++++++-
 templating/matrix_templates/sections.py | 21 +++++++++---
 2 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/api/client-server/v1/profile.yaml b/api/client-server/v1/profile.yaml
index 58f9e108..e19466bf 100644
--- a/api/client-server/v1/profile.yaml
+++ b/api/client-server/v1/profile.yaml
@@ -61,6 +61,10 @@ paths:
             "$ref": "definitions/error.yaml"
     get:
       summary: Get the user's display name.
+      description: |-
+        Get the user's display name. This API may be used to fetch the user's
+        own displayname or to query the name of other users; either locally or
+        on remote homeservers.
       parameters:
         - in: path
           type: string
@@ -127,6 +131,10 @@ paths:
             "$ref": "definitions/error.yaml"
     get:
       summary: Get the user's avatar URL.
+      description: |-
+        Get the user's avatar URL. This API may be used to fetch the user's
+        own avatar URL or to query the URL of other users; either locally or
+        on remote homeservers.
       parameters:
         - in: path
           type: string
@@ -149,4 +157,39 @@ paths:
                 type: string
                 description: The user's avatar URL if they have set one.
         404:
-          description: There is no avatar URL for this user or this user does not exist.
\ No newline at end of file
+          description: There is no avatar URL for this user or this user does not exist.
+  "/profile/{userId}":
+    get:
+      summary: Get this user's profile information.
+      description: |-
+        Get the combined profile information for this user. This API may be used
+        to fetch the user's own profile information or other users; either
+        locally or on remote homeservers. This API may return keys which are not
+        limited to ``displayname`` or ``avatar_url``.
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose avatar URL to get.
+          required: true
+          x-example: "@alice:example.com"
+      responses:
+        200:
+          description: The avatar URL for this user.
+          examples:
+            application/json: |-
+              {
+                "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                "displayname": "Alice Margatroid"
+              }
+          schema:
+            type: object
+            properties:
+              avatar_url:
+                type: string
+                description: The user's avatar URL if they have set one.
+              displayname:
+                type: string
+                description: The user's display name if they have set one.
+        404:
+          description: There is no profile information for this user or this user does not exist.
\ No newline at end of file
diff --git a/templating/matrix_templates/sections.py b/templating/matrix_templates/sections.py
index c9c6eeda..0c29070a 100644
--- a/templating/matrix_templates/sections.py
+++ b/templating/matrix_templates/sections.py
@@ -30,17 +30,30 @@ class MatrixSections(Sections):
             ))
         return "\n\n".join(sections)
 
-    def render_foo(self):
+    def _render_http_api_group(self, group, sortFn=sorted, title_kind="-"):
         template = self.env.get_template("http-api.tmpl")
-        http_api = self.units.get("swagger_apis")["profile"]["__meta"]
+        http_api = self.units.get("swagger_apis")[group]["__meta"]
         sections = []
-        for endpoint in http_api["endpoints"]:
+        for endpoint in sortFn(http_api["endpoints"]):
             sections.append(template.render(
                 endpoint=endpoint,
-                title_kind="-"
+                title_kind=title_kind
             ))
         return "\n\n".join(sections)
 
+    def render_profile_http_api(self):
+        def sortFn(endpoints):
+            ordering = ["displayname", "avatar_url"]
+            sorted_endpoints = []
+            for path_substr in ordering:
+                for e in endpoints:
+                    if path_substr in e["path"]:
+                        sorted_endpoints.append(e)  # could have multiple
+            # dump rest
+            rest = [ e for e in endpoints if e not in sorted_endpoints ]
+            return sorted_endpoints + rest
+        return self._render_http_api_group("profile", sortFn=sortFn)
+
     def render_room_events(self):
         def filterFn(eventType):
             return (