From 89384c96c18310d084fa3c2695c51109780b9f53 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 18 Jul 2018 11:06:23 -0600 Subject: [PATCH] Full stops, language. --- api/server-server/definitions/edu.yaml | 10 ++++----- api/server-server/definitions/pdu.yaml | 8 +++---- .../definitions/transaction.yaml | 6 ++--- .../definitions/unsigned_pdu.yaml | 22 +++++++++---------- api/server-server/events.yaml | 21 +++++++++--------- 5 files changed, 34 insertions(+), 33 deletions(-) diff --git a/api/server-server/definitions/edu.yaml b/api/server-server/definitions/edu.yaml index 4597ca62..af12752c 100644 --- a/api/server-server/definitions/edu.yaml +++ b/api/server-server/definitions/edu.yaml @@ -22,16 +22,16 @@ example: properties: edu_type: type: string - description: The type of ephemeral message - example: "!abc123:matrix.org" + description: The type of ephemeral message. + example: "m.presence" origin: type: string - description: The server name sending the ephemeral message + description: The server name sending the ephemeral message. example: "matrix.org" destination: type: string - description: The server name receiving the ephemeral message + description: The server name receiving the ephemeral message. example: "elsewhere.com" content: type: object - description: The content of the ephemeral message + description: The content of the ephemeral message. diff --git a/api/server-server/definitions/pdu.yaml b/api/server-server/definitions/pdu.yaml index 2b6328be..a5da57c0 100644 --- a/api/server-server/definitions/pdu.yaml +++ b/api/server-server/definitions/pdu.yaml @@ -23,20 +23,20 @@ allOf: hashes: type: object title: Event Hash - description: Hashes of the PDU, following the algorithm specified in `Signing Events`_ + description: Hashes of the PDU, following the algorithm specified in `Signing Events`_. example: { "sha256": "thishashcoversallfieldsincasethisisredacted" } properties: sha256: type: string - description: The hash - example: thishashcoversallfieldsincasethisisredacted + description: The hash. + example: thishashcoversallfieldsincasthisisredacted required: ['sha256'] signatures: type: object description: |- - Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_ + Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_. example: { "example.com": { "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml index 630d2ba3..e4c1f559 100644 --- a/api/server-server/definitions/transaction.yaml +++ b/api/server-server/definitions/transaction.yaml @@ -20,16 +20,16 @@ properties: origin: type: string description: |- - The ``server_name`` of hoemserver sending this transaction + The ``server_name`` of the hoemserver sending this transaction. example: "example.org" origin_server_ts: type: integer format: int64 - description: Timestamp in milliseconds on originating homeserver when this transaction started + description: Timestamp in milliseconds on originating homeserver when this transaction started. example: 1234567890 pdus: type: array - description: List of persistent updates to rooms + description: List of persistent updates to rooms. items: $ref: "pdu.yaml" required: ['origin', 'origin_server_ts', 'pdus'] \ No newline at end of file diff --git a/api/server-server/definitions/unsigned_pdu.yaml b/api/server-server/definitions/unsigned_pdu.yaml index 173bddd4..ca0a1183 100644 --- a/api/server-server/definitions/unsigned_pdu.yaml +++ b/api/server-server/definitions/unsigned_pdu.yaml @@ -19,15 +19,15 @@ example: properties: room_id: type: string - description: Room identifier + description: Room identifier. example: "!abc123:matrix.org" sender: type: string - description: The ID of the user sending the event + description: The ID of the user sending the event. example: "@someone:matrix.org" origin: type: string - description: The ``server_name`` of the homeserver that created this event + description: The ``server_name`` of the homeserver that created this event. example: "matrix.org" origin_server_ts: type: integer @@ -47,13 +47,13 @@ properties: example: "my_key" content: type: object - description: The content of the event + description: The content of the event. example: {"key": "value"} prev_events: type: array description: |- Event IDs and hashes of the most recent events in the room that the homeserver was aware - of when it made this event + of when it made this event. items: type: array maxItems: 2 @@ -70,16 +70,16 @@ properties: properties: sha256: type: string - description: The event hash + description: The event hash. example: abase64encodedsha256hashshouldbe43byteslong required: ['sha256'] depth: type: integer - description: The maximum depth of the ``prev_events``, plus one + description: The maximum depth of the ``prev_events``, plus one. example: 12 auth_events: type: array - description: Event IDs and hashes for the "auth events" of this event + description: Event IDs and hashes for the "auth events" of this event. items: type: array maxItems: 2 @@ -96,16 +96,16 @@ properties: properties: sha256: type: string - description: The event hash + description: The event hash. example: abase64encodedsha256hashshouldbe43byteslong required: ['sha256'] redacts: type: string - description: For redaction events, the ID of the event being redacted + description: For redaction events, the ID of the event being redacted. example: "$def456:matrix.org" unsigned: type: object - description: Additional data added by the origin server but not covered by the ``signatures`` + description: Additional data added by the origin server but not covered by the ``signatures``. example: {"key": "value"} required: - room_id diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index 055883c2..08498c35 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -33,37 +33,37 @@ paths: - in: path name: roomId type: string - description: The room ID to get state for + description: The room ID to get state for. required: true x-example: "!abc123:matrix.org" responses: 200: - description: The room state for the room (kept under ``pdus``) + description: The room state for the room (kept under ``pdus``). schema: $ref: "definitions/transaction.yaml" "/event/{eventId}": get: summary: Get a single event description: |- - Retrieves a single event + Retrieves a single event. operationId: getEvent parameters: - in: path name: eventId type: string - description: The event ID to get + description: The event ID to get. required: true x-example: "$abc123:matrix.org" responses: 200: - description: A transaction containing a single PDU which is the event requested + description: A transaction containing a single PDU which is the event requested. schema: $ref: "definitions/transaction.yaml" "/backfill/{roomId}": get: summary: Retrieves the events which precede the given event description: |- - Retreives a sliding-window history of previous PDUs that occurred on the given room. + Retreives a sliding-window history of previous PDUs that occurred in the given room. Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it are retrived, up to the total number given by the ``limit``. operationId: backfillRoom @@ -71,19 +71,19 @@ paths: - in: path name: roomId type: string - description: The room ID to backfill + description: The room ID to backfill. required: true x-example: "!abc123:matrix.org" - in: query name: v type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it - description: The event ID to backfill from + description: The event ID to backfill from. required: true x-example: "$abc123:matrix.org" - in: query name: limit type: integer - description: The maximum number of events to retrieve + description: The maximum number of events to retrieve. required: true # TODO: Verify x-example: 10 responses: @@ -91,6 +91,7 @@ paths: description: A transaction containing the PDUs that preceded the given event(s). schema: $ref: "definitions/transaction.yaml" + # TODO: It's possible that this endpoint doesn't exist anymore - verify "/pull": get: summary: Stream events later than a given point in history @@ -101,7 +102,7 @@ paths: - in: query name: v type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it - description: The event ID to backfill from + description: The event ID to backfill from. required: true x-example: "$abc123:matrix.org" - in: query