diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 7b6c94713..78aebddc9 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -4,8 +4,10 @@ .. "v.." - You cannot use a-z. If the templating system fails to .. find the right info, it will be treated as a test failure and so will show up .. in Jenkins. Comments like this are ignored by both RST and the templating -.. system. +.. system. Add the newest release notes beneath this comment. Specification changes in v0.1.0 (2015-06-01) ============================================ -- First numbered release. \ No newline at end of file +- First numbered release. +- Restructure the format of Event information. Add more information. +- Restructure the format of the Client-Server HTTP APIs. \ No newline at end of file diff --git a/api/client-server/v1/content-repo.yaml b/api/client-server/v1/content-repo.yaml index d7d4fb6ce..fe3d1dc37 100644 --- a/api/client-server/v1/content-repo.yaml +++ b/api/client-server/v1/content-repo.yaml @@ -54,7 +54,6 @@ paths: description: "The content downloaded." schema: type: file - name: content "/thumbnail/{serverName}/{mediaId}": get: summary: "Download a thumbnail of the content from the content repository." @@ -90,6 +89,5 @@ paths: description: "A thumbnail of the requested content." schema: type: file - name: content diff --git a/api/client-server/v1/definitions/event.yaml b/api/client-server/v1/definitions/event.yaml new file mode 100644 index 000000000..cfb1b924c --- /dev/null +++ b/api/client-server/v1/definitions/event.yaml @@ -0,0 +1,7 @@ +type: object +description: A Matrix Event +properties: + event_id: + type: string + description: An event ID. +required: ["event_id"] \ No newline at end of file diff --git a/api/client-server/v1/definitions/room_event.yaml b/api/client-server/v1/definitions/room_event.yaml new file mode 100644 index 000000000..5a9e3a09c --- /dev/null +++ b/api/client-server/v1/definitions/room_event.yaml @@ -0,0 +1,9 @@ +type: object +description: A Matrix Room Event +properties: + event_id: + type: string + description: An event ID. + room_id: + type: string +required: ["event_id", "room_id"] \ No newline at end of file diff --git a/api/client-server/v1/definitions/state_event.yaml b/api/client-server/v1/definitions/state_event.yaml new file mode 100644 index 000000000..f8e6f4d4e --- /dev/null +++ b/api/client-server/v1/definitions/state_event.yaml @@ -0,0 +1,11 @@ +type: object +description: A Matrix State Event +properties: + event_id: + type: string + description: An event ID. + room_id: + type: string + state_key: + type: string +required: ["event_id", "room_id", "state_key"] \ No newline at end of file diff --git a/api/client-server/v1/sync.yaml b/api/client-server/v1/sync.yaml new file mode 100644 index 000000000..a08146b47 --- /dev/null +++ b/api/client-server/v1/sync.yaml @@ -0,0 +1,350 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server v1 Sync API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/api/v1 +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: + "/events": + get: + summary: Listen on the event stream. + description: |- + This will listen for new events and return them to the caller. This will + block until an event is received, or until the ``timeout`` is reached. + security: + - accessToken: [] + parameters: + - in: query + type: string + name: from + description: The token to stream from. + required: false + x-example: "s3456_9_0" + - in: query + type: integer + name: timeout + description: The maximum time in milliseconds to wait for an event. + required: false + x-example: "35000" + responses: + 200: + description: "The events received, which may be none." + examples: + application/json: |- + { + "start": "s3456_9_0", + "end": "s3457_9_0", + "chunk": [ + { + "age": 32, + "content": { + "body": "incoming message", + "msgtype": "m.text" + }, + "event_id": "$14328055551tzaee:localhost", + "origin_server_ts": 1432804485886, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "type": "m.room.message", + "user_id": "@bob:localhost" + } + ] + } + schema: + type: object + properties: + start: + type: string + description: |- + A token which correlates to the first value in ``chunk``. Used + for pagination. + end: + type: string + description: |- + A token which correlates to the last value in ``chunk``. Used + for pagination. + chunk: + type: array + description: "An array of events." + items: + type: object + title: RoomEvent + allOf: + - "$ref": "definitions/room_event.yaml" + 400: + description: "Bad pagination ``from`` parameter." + "/initialSync": + get: + summary: Get the user's current state. + description: |- + This returns the full state for this user, with an optional limit on the + number of messages per room to return. + security: + - accessToken: [] + parameters: + - in: query + type: integer + name: limit + description: The maximum number of messages to return for each room. + required: false + x-example: "2" + responses: + 200: + description: The user's current state. + examples: + application/json: |- + { + "end": "s3456_9_0", + "presence": [ + { + "content": { + "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto", + "displayname": "Bob", + "last_active_ago": 31053, + "presence": "online", + "user_id": "@bob:localhost" + }, + "type": "m.presence" + } + ], + "rooms": [ + { + "membership": "join", + "messages": { + "chunk": [ + { + "age": 343513403, + "content": { + "body": "foo", + "msgtype": "m.text" + }, + "event_id": "$14328044851tzTJS:localhost", + "origin_server_ts": 1432804485886, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "type": "m.room.message", + "user_id": "@alice:localhost" + }, + { + "age": 343511809, + "content": { + "body": "bar", + "msgtype": "m.text" + }, + "event_id": "$14328044872spjFg:localhost", + "origin_server_ts": 1432804487480, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "type": "m.room.message", + "user_id": "@bob:localhost" + } + ], + "end": "s3456_9_0", + "start": "t44-3453_9_0" + }, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state": [ + { + "age": 7148266897, + "content": { + "join_rule": "public" + }, + "event_id": "$14259997323TLwtb:localhost", + "origin_server_ts": 1425999732392, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state_key": "", + "type": "m.room.join_rules", + "user_id": "@alice:localhost" + }, + { + "age": 6547561012, + "content": { + "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto", + "displayname": null, + "membership": "join" + }, + "event_id": "$1426600438280zExKY:localhost", + "membership": "join", + "origin_server_ts": 1426600438277, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state_key": "@alice:localhost", + "type": "m.room.member", + "user_id": "@alice:localhost" + }, + { + "age": 7148267200, + "content": { + "creator": "@alice:localhost" + }, + "event_id": "$14259997320KhbwJ:localhost", + "origin_server_ts": 1425999732089, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state_key": "", + "type": "m.room.create", + "user_id": "@alice:localhost" + }, + { + "age": 1622568720, + "content": { + "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto", + "displayname": "Bob", + "membership": "join" + }, + "event_id": "$1431525430134MxlLX:localhost", + "origin_server_ts": 1431525430569, + "replaces_state": "$142652023736BSXcM:localhost", + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state_key": "@bob:localhost", + "type": "m.room.member", + "user_id": "@bob:localhost" + }, + { + "age": 7148267004, + "content": { + "ban": 50, + "events": { + "m.room.name": 100, + "m.room.power_levels": 100 + }, + "events_default": 0, + "kick": 50, + "redact": 50, + "state_default": 50, + "users": { + "@alice:localhost": 100 + }, + "users_default": 0 + }, + "event_id": "$14259997322mqfaq:localhost", + "origin_server_ts": 1425999732285, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state_key": "", + "type": "m.room.power_levels", + "user_id": "@alice:localhost" + } + ], + "visibility": "private" + } + ] + } + schema: + type: object + properties: + end: + type: string + description: |- + A token which correlates to the last value in ``chunk``. This + token should be used with the ``/events`` API to listen for new + events. + presence: + type: array + description: A list of presence events. + items: + type: object + title: Event + allOf: + - "$ref": "definitions/event.yaml" + rooms: + type: array + items: + type: object + title: RoomInfo + properties: + room_id: + type: string + description: "The ID of this room." + membership: + type: string + description: "The user's membership state in this room." + enum: ["invite", "join", "leave", "ban"] + messages: + type: object + title: PaginationChunk + description: "The pagination chunk for this room." + properties: + start: + type: string + description: |- + A token which correlates to the first value in ``chunk``. + Used for pagination. + end: + type: string + description: |- + A token which correlates to the last value in ``chunk``. + Used for pagination. + chunk: + type: array + description: |- + A list of the most recent messages for this room. This + array will consist of at most ``limit`` elements. + items: + type: object + title: RoomEvent + allOf: + - "$ref": "definitions/room_event.yaml" + required: ["start", "end", "chunk"] + state: + type: array + description: |- + A list of state events representing the current state + of the room. + items: + title: StateEvent + type: object + allOf: + - "$ref": "definitions/state_event.yaml" + visibility: + type: string + enum: ["private", "public"] + description: |- + Whether this room is visible to the ``/publicRooms`` API + or not." + required: ["room_id", "membership"] + required: ["end", "rooms", "presence"] + 404: + description: There is no avatar URL for this user or this user does not exist. + "/events/{eventId}": + get: + summary: Get a single event by event ID. + description: |- + Get a single event based on ``event_id``. You must have permission to + retrieve this event e.g. by being a member in the room for this event. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: eventId + description: The event ID to get. + required: true + x-example: "$asfDuShaf7Gafaw:matrix.org" + responses: + 200: + description: The full event. + examples: + application/json: |- + { + "content": { + "body": "Hello world!", + "msgtype": "m.text" + }, + "room_id:" "!wfgy43Sg4a:matrix.org", + "user_id": "@bob:matrix.org", + "event_id": "$asfDuShaf7Gafaw:matrix.org", + "type": "m.room.message" + } + schema: + allOf: + - "$ref": "definitions/event.yaml" + 404: + description: The event was not found or you do not have permission to read this event. \ No newline at end of file diff --git a/templating/matrix_templates/sections.py b/templating/matrix_templates/sections.py index 02bc1715d..637597554 100644 --- a/templating/matrix_templates/sections.py +++ b/templating/matrix_templates/sections.py @@ -61,6 +61,11 @@ class MatrixSections(Sections): "profile", sortFn=sortFn, title_kind="+" ) + def render_sync_http_api(self): + return self._render_http_api_group( + "sync" + ) + def render_room_events(self): def filterFn(eventType): return ( diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 9b340f5e0..41a620990 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -204,7 +204,7 @@ class MatrixUnits(Units): elif param["in"] == "body": body = param["schema"]["example"] elif param["in"] == "query": - qps[param["name"]] = qps[param["x-example"]] + qps[param["name"]] = param["x-example"] query_string = "" if len(qps) == 0 else "?"+urllib.urlencode(qps) endpoint["example"]["req"] = "%s %s%s\n%s" % ( method.upper(), path_template, query_string, body