matrix-spec-proposals/api/server-server/transactions.yaml

# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

swagger: '2.0'
info:
  title: "Matrix Federation Transaction API"
  version: "1.0.0"
host: localhost:8448
schemes:
  - https
basePath: /_matrix/federation/v1
consumes:
  - application/json
produces:
  - application/json
paths:
  "/send/{txnId}":
    put:
      summary: Send a transaction
      description: |-
        Push messages representing live activity to another server. The destination name
        will be set to that of the receiving server itself. Each embedded PDU in the
        transaction body will be processed.

        The sending server must wait and retry for a 200 OK response before sending a
        transaction with a different ``txnId`` to the receiving server.        
      operationId: sendTransaction
      parameters:
        - in: path
          name: txnId
          type: string
          description: |-
                        The transaction ID.
          required: true
          x-example: S0meTransacti0nId
        - in: body
          name: body
          type: object
          required: true
          schema:
            allOf:
              - $ref: "definitions/transaction.yaml"
              - type: object
                properties:
                  edus:
                    type: array
                    description: |-
                      List of ephemeral messages. May be omitted if there are no ephemeral 
                      messages to be sent.                      
                    items:
                      $ref: "definitions/edu.yaml"
          example: {
            "$ref": "examples/transaction.json",
            "edus": [{"$ref": "edu.json"}] # Relative to the examples directory
          }
      responses:
        200:
          description: |-
            The result of processing the transaction. The server is to use this response even in
            the event of one or more PDUs failing to be processed.            
          schema:
            type: array
            minItems: 2
            maxItems: 2
            items:
              - type: integer
                description: The value ``200``.
                example: 200
              - type: object
                title: PDU Processing Results
                description: The results for the processing of each PDU in the transaction.
                properties:
                  pdus:
                    type: object
                    description: |-
                      The PDUs from the original transaction. The string key represents the ID of the
                      PDU (event) that was processed.                      
                    additionalProperties:
                      type: object
                      title: PDU Processing Result
                      description: Information about how the PDU was handled.
                      properties:
                        error:
                          type: string
                          description: |-
                            A human readable description about what went wrong in processing this PDU.
                            If no error is present, the PDU can be considered successfully handled.                            
                          example: "You are not allowed to send a message to this room."
                required: ['pdus']
          examples:
            application/json: [
              200,
              {
                "pdus": {
                  "$successful_event:domain.com": {},
                  "$failed_event:example.org": {
                    "error": "You are not allowed to send a message to this room."
                  }
                }
              }
            ]