From f4f186baeebb2901583f82fa404b80c28a4691b1 Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Tue, 8 Mar 2016 17:42:41 +0000 Subject: [PATCH] Add _cs suffix to client-server http APIs I'm about to add identity service APIs, so differentiating is good. --- .gitignore | 1 + specification/application_service_api.rst | 2 +- specification/client_server_api.rst | 42 +++++++++---------- specification/modules/_template.rst | 4 +- specification/modules/account_data.rst | 2 +- specification/modules/admin.rst | 2 +- specification/modules/content_repo.rst | 2 +- specification/modules/event_context.rst | 2 +- specification/modules/presence.rst | 2 +- specification/modules/push.rst | 4 +- specification/modules/receipts.rst | 2 +- specification/modules/room_previews.rst | 2 +- specification/modules/search.rst | 2 +- specification/modules/tags.rst | 2 +- specification/modules/third_party_invites.rst | 2 +- .../modules/typing_notifications.rst | 2 +- specification/modules/voip_events.rst | 2 +- templating/matrix_templates/sections.py | 6 +-- templating/matrix_templates/units.py | 8 +++- 19 files changed, 48 insertions(+), 43 deletions(-) diff --git a/.gitignore b/.gitignore index 74b1c7d2..eb8e8808 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ scripts/continuserv/continuserv scripts/speculator/speculator templating/out *.pyc +*.swp supporting-docs/_site supporting-docs/.sass-cache api/node_modules diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index cf45be08..6d983461 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -149,7 +149,7 @@ HTTP APIs This contains application service APIs which are used by the homeserver. All application services MUST implement these APIs. These APIs are defined below. -{{application_service_http_api}} +{{application_service_as_http_api}} .. _create the user: `sect:asapi-permissions`_ diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 15c3eb9e..0273bb56 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -111,7 +111,7 @@ Some API endpoints may allow or require the use of ``POST`` requests without a transaction ID. Where this is optional, the use of a ``PUT`` request is strongly recommended. -{{versions_http_api}} +{{versions_cs_http_api}} Client Authentication --------------------- @@ -481,9 +481,9 @@ API calls using the User-Interactive Authentication mechanism ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _User-Interactive Authentication: `sect:auth-api`_ -{{registration_http_api}} +{{registration_cs_http_api}} -{{login_http_api}} +{{login_cs_http_api}} Login Fallback ++++++++++++++ @@ -525,7 +525,7 @@ Adding Account Administrative Contact Information A homeserver may keep some contact information for administrative use. This is independent of any information kept by any Identity Servers. -{{administrative_contact_http_api}} +{{administrative_contact_cs_http_api}} Pagination ---------- @@ -628,7 +628,7 @@ Filters can be created on the server and can be passed as as a parameter to APIs which return events. These filters alter the data returned from those APIs. Not all APIs accept filters. -{{filter_http_api}} +{{filter_cs_http_api}} Events ------ @@ -750,9 +750,9 @@ When the client first logs in, they will need to initially synchronise with their homeserver. This is achieved via the initial sync API described below. This API also returns an ``end`` token which can be used with the event stream. -{{old_sync_http_api}} +{{old_sync_cs_http_api}} -{{sync_http_api}} +{{sync_cs_http_api}} Getting events for a room @@ -760,16 +760,16 @@ Getting events for a room There are several APIs provided to ``GET`` events for a room: -{{rooms_http_api}} +{{rooms_cs_http_api}} -{{message_pagination_http_api}} +{{message_pagination_cs_http_api}} Sending events to a room ~~~~~~~~~~~~~~~~~~~~~~~~ -{{room_state_http_api}} +{{room_state_cs_http_api}} **Examples** @@ -806,7 +806,7 @@ In some cases, there may be no need for a ``state_key``, so it can be omitted:: PUT /rooms/!roomid:domain/state/m.room.bgd.color { "color": "red", "hex": "#ff0000" } -{{room_send_http_api}} +{{room_send_cs_http_api}} Redactions @@ -855,7 +855,7 @@ Events Client behaviour ++++++++++++++++ -{{redaction_http_api}} +{{redaction_cs_http_api}} Rooms ----- @@ -875,7 +875,7 @@ includes: See `Room Events`_ for more information on these events. To create a room, a client has to use the following API. -{{create_room_http_api}} +{{create_room_cs_http_api}} Room aliases ~~~~~~~~~~~~ @@ -901,7 +901,7 @@ request. Homeservers can respond to resolve requests for aliases on other domains than their own by using the federation API to ask other domain name homeservers. -{{directory_http_api}} +{{directory_cs_http_api}} Permissions @@ -980,13 +980,13 @@ The allowable state transitions of membership are:: /ban -{{inviting_http_api}} +{{inviting_cs_http_api}} -{{joining_http_api}} +{{joining_cs_http_api}} -{{kicking_http_api}} +{{kicking_cs_http_api}} -{{banning_http_api}} +{{banning_cs_http_api}} Leaving rooms ~~~~~~~~~~~~~ @@ -999,7 +999,7 @@ Whether or not they actually joined the room, if the room is an "invite-only" room they will need to be re-invited before they can re-join the room. -{{leaving_http_api}} +{{leaving_cs_http_api}} Banning users in a room ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1030,12 +1030,12 @@ before they can re-join the room or be re-invited. Listing rooms ~~~~~~~~~~~~~ -{{list_public_rooms_http_api}} +{{list_public_rooms_cs_http_api}} Profiles -------- -{{profile_http_api}} +{{profile_cs_http_api}} Events on Change of Profile Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/specification/modules/_template.rst b/specification/modules/_template.rst index 9eee9843..dd86febe 100644 --- a/specification/modules/_template.rst +++ b/specification/modules/_template.rst @@ -31,10 +31,10 @@ Client behaviour ---------------- List any new HTTP endpoints. These endpoints should be documented using Swagger. Once there is Swagger, there will be a template variable based on the name of -the YAML file with the suffix ``_http_api``. You can insert a template for +the YAML file with the suffix ``_cs_http_api``. You can insert a template for swagger docs like so: -{{name-of-yaml-file-without-file-ext_http_api}} +{{name-of-yaml-file-without-file-ext_cs_http_api}} List the steps the client needs to take to correctly process this module. List what data structures the client should be diff --git a/specification/modules/account_data.rst b/specification/modules/account_data.rst index e7c650ac..15885997 100644 --- a/specification/modules/account_data.rst +++ b/specification/modules/account_data.rst @@ -24,4 +24,4 @@ the tags are for. Client Behaviour ---------------- -{{account_data_http_api}} +{{account_data_cs_http_api}} diff --git a/specification/modules/admin.rst b/specification/modules/admin.rst index 45d1064f..6dc8061a 100644 --- a/specification/modules/admin.rst +++ b/specification/modules/admin.rst @@ -9,4 +9,4 @@ and data. Client Behaviour ---------------- -{{admin_http_api}} +{{admin_cs_http_api}} diff --git a/specification/modules/content_repo.rst b/specification/modules/content_repo.rst index e07cf58c..b83fdcfc 100644 --- a/specification/modules/content_repo.rst +++ b/specification/modules/content_repo.rst @@ -24,7 +24,7 @@ Client behaviour Clients can upload and download content using the following HTTP APIs. -{{content_repo_http_api}} +{{content_repo_cs_http_api}} Thumbnails ~~~~~~~~~~ diff --git a/specification/modules/event_context.rst b/specification/modules/event_context.rst index a972e6fa..0d93ae34 100644 --- a/specification/modules/event_context.rst +++ b/specification/modules/event_context.rst @@ -11,7 +11,7 @@ Client behaviour There is a single HTTP API for retrieving event context, documented below. -{{event_context_http_api}} +{{event_context_cs_http_api}} Security considerations ----------------------- diff --git a/specification/modules/presence.rst b/specification/modules/presence.rst index 4eddaeee..e00040da 100644 --- a/specification/modules/presence.rst +++ b/specification/modules/presence.rst @@ -44,7 +44,7 @@ Client behaviour Clients can manually set/get their presence/presence list using the HTTP APIs listed below. -{{presence_http_api}} +{{presence_cs_http_api}} Idle timeout ~~~~~~~~~~~~ diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 2a8308d8..b14359b6 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -89,7 +89,7 @@ Client behaviour Clients MUST configure a Pusher before they will receive push notifications. There is a single API endpoint for this, as described below. -{{pusher_http_api}} +{{pusher_cs_http_api}} .. _pushers: `def:pushers`_ @@ -334,7 +334,7 @@ Push Rules: API Clients can retrieve, add, modify and remove push rules globally or per-device using the APIs below. -{{pushrules_http_api}} +{{pushrules_cs_http_api}} Examples ++++++++ diff --git a/specification/modules/receipts.rst b/specification/modules/receipts.rst index 70135801..c8c58ff2 100644 --- a/specification/modules/receipts.rst +++ b/specification/modules/receipts.rst @@ -52,7 +52,7 @@ dismissing a notification in order for the event to count as "read". A client can update the markers for its user by interacting with the following HTTP APIs. -{{receipts_http_api}} +{{receipts_cs_http_api}} Server behaviour ---------------- diff --git a/specification/modules/room_previews.rst b/specification/modules/room_previews.rst index a27c7fb7..e47fa9c8 100644 --- a/specification/modules/room_previews.rst +++ b/specification/modules/room_previews.rst @@ -27,7 +27,7 @@ events outside the ``/events`` stream. .. _peeking_events_api: -{{peeking_events_http_api}} +{{peeking_events_cs_http_api}} Server behaviour ---------------- diff --git a/specification/modules/search.rst b/specification/modules/search.rst index bb8f0141..b2ae6a63 100644 --- a/specification/modules/search.rst +++ b/specification/modules/search.rst @@ -12,7 +12,7 @@ Client behaviour ---------------- There is a single HTTP API for performing server-side search, documented below. -{{search_http_api}} +{{search_cs_http_api}} Search Categories ----------------- diff --git a/specification/modules/tags.rst b/specification/modules/tags.rst index 4bed9657..1faf894a 100644 --- a/specification/modules/tags.rst +++ b/specification/modules/tags.rst @@ -45,4 +45,4 @@ Two special names are listed in the specification: Client Behaviour ---------------- -{{tags_http_api}} +{{tags_cs_http_api}} diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index d8e3d4d9..bcc5e93b 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -36,7 +36,7 @@ Client behaviour A client asks a server to invite a user by their third party identifier. -{{third_party_membership_http_api}} +{{third_party_membership_cs_http_api}} Server behaviour ---------------- diff --git a/specification/modules/typing_notifications.rst b/specification/modules/typing_notifications.rst index 8be1ac28..3bef79d2 100644 --- a/specification/modules/typing_notifications.rst +++ b/specification/modules/typing_notifications.rst @@ -32,7 +32,7 @@ expected timeout runs out is recommended. When the user stops typing, the state change of the ``boolean`` to ``false`` should trigger another HTTP request to inform the server that the user has stopped typing. -{{typing_http_api}} +{{typing_cs_http_api}} Security considerations ----------------------- diff --git a/specification/modules/voip_events.rst b/specification/modules/voip_events.rst index 348aad62..6c7dbb5e 100644 --- a/specification/modules/voip_events.rst +++ b/specification/modules/voip_events.rst @@ -90,7 +90,7 @@ The homeserver MAY provide a TURN server which clients can use to contact the remote party. The following HTTP API endpoints will be used by clients in order to get information about the TURN server. -{{voip_http_api}} +{{voip_cs_http_api}} Security considerations diff --git a/templating/matrix_templates/sections.py b/templating/matrix_templates/sections.py index 867749bf..2db10a2f 100644 --- a/templating/matrix_templates/sections.py +++ b/templating/matrix_templates/sections.py @@ -57,7 +57,7 @@ class MatrixSections(Sections): rest = [ e for e in http_api["endpoints"] if e not in sorted_endpoints ] - endpoints = sorted_endpoints + rest + endpoints = sorted_endpoints + sorted(rest, key=lambda k: k["path"]) else: # guess it's a func, call it. endpoints = sortFnOrPathList(http_api["endpoints"]) @@ -81,9 +81,9 @@ class MatrixSections(Sections): renders = {} for group in swagger_groups: sortFnOrPathList = None - if group == "presence": + if group == "presence_cs": sortFnOrPathList = ["status"] - elif group == "profile": + elif group == "profile_cs": sortFnOrPathList=["displayname", "avatar_url"] renders[group + "_http_api"] = self._render_http_api_group( group, sortFnOrPathList diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 013a0b10..726d9169 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -17,7 +17,10 @@ import subprocess import urllib import yaml -HTTP_APIS = ("../api/application-service", "../api/client-server",) +HTTP_APIS = { + "../api/application-service": "as", + "../api/client-server": "cs", +} EVENT_EXAMPLES = "../event-schemas/examples" EVENT_SCHEMA = "../event-schemas/schema" CORE_EVENT_SCHEMA = "../event-schemas/schema/core-event-schema" @@ -474,7 +477,7 @@ class MatrixUnits(Units): def load_swagger_apis(self): apis = {} - for path in HTTP_APIS: + for path, suffix in HTTP_APIS.items(): for filename in os.listdir(path): if not filename.endswith(".yaml"): continue @@ -483,6 +486,7 @@ class MatrixUnits(Units): with open(filepath, "r") as f: # strip .yaml group_name = filename[:-5].replace("-", "_") + group_name = "%s_%s" % (group_name, suffix) api = yaml.load(f.read()) api = resolve_references(filepath, api) api["__meta"] = self._load_swagger_meta(