openapi: 3.0.1
info:
  title: Platform API
  description: The [REST API specification](https://www.ably.io/documentation/rest-api) for Ably.
  version: "1.1.0"
  contact:
    name: "Ably Support"
    url: "https://www.ably.io/contact"
    email: "support@ably.io"
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic Authentication using an [API key](https://www.ably.io/documentation/core-features/authentication#basic-authentication).
    bearerAuth:
      type: http
      scheme: bearer
      description: Token Authentication using an [Ably Token](https://www.ably.io/documentation/core-features/authentication#basic-authentication), or optionally an [Ably JWT](https://www.ably.io/documentation/core-features/authentication#ably-jwt-process).

  headers:
    # TODO: Issue exists for integrating pagination with OpenAPI, https://github.com/OAI/OpenAPI-Specification/issues/667. If this is ever actioned, we should enable it within our spec.
    Link:
      description: Links to related resources, in the format defined by [RFC 5988](https://tools.ietf.org/html/rfc5988#section-5). This will potentially include a link with relation type `next`, `first`, and `current`, where appropiate.
      schema:
        type: string
        pattern: '(<(.*)?>; rel=\"(first|current|last)?\",)*(<(.*)?>; rel=\"(first|current|last)?\")+'
      required: true

    ServerId:
      description: The ID for the server communicated with.
      schema:
        type: string
      required: true

    ErrorCode:
      description: The error code.
      schema:
        type: integer

    ErrorMessage:
      description: The error message.
      schema:
        type: string

  parameters:
    # Currently each parameter needs to be defined seperately. If https://github.com/OAI/OpenAPI-Specification/issues/445 ever goes through, can amalagmate pagination parameters
    filterStart:
      name: start
      in: query
      schema:
        type: string

    filterLimit:
      name: limit
      in: query
      schema:
        type: integer
        default: '100'

    filterEnd:
      name: end
      in: query
      schema:
        type: string
        default: now

    filterDirection:
      name: direction
      in: query
      schema:
        type: string
        default: backwards
        enum: [forwards, backwards ]

    channelId:
      name: channel_id
      in: path
      schema:
        type: string
      required: true
      description: The [Channel's ID](https://www.ably.io/documentation/rest/channels).

    # TODO: Better document what the name is
    key_name:
      name: keyName
      in: path
      schema:
        type: string
      required: true
      description: The [key name](https://www.ably.io/documentation/rest-api/token-request-spec#api-key-format) comprises of the app ID and key ID of an API key.

    deviceId:
      name: device_id
      in: path
      schema:
        type: string
      required: true
      description: Device's ID.

    versionHeader:
      in: header
      name: X-Ably-Version
      schema:
        type: string
      description: The version of the API you wish to use.

    responseFormat:
      in: query
      name: format
      schema:
        type: string
        enum:
          - json
          - jsonp
          - msgpack
          - html
      description: The response format you would like

  schemas:
    # Message components
    Message:
      type: object
      description: Message object.
      properties:
        name:
          description: The event name, if provided.
          type: string
        data:
          description: The string encoded payload, with the encoding specified below.
          type: string
        id:
          description: A Unique ID that can be specified by the publisher for [idempotent publishing](https://www.ably.io/documentation/rest/messages#idempotent).
          type: string
          readOnly: true
        timestamp:
          description: Timestamp when the message was received by the Ably, as milliseconds since the epoch.
          type: integer
          format: int64
          readOnly: true
        encoding:
          description: This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload.
          type: string
        clientId:
          description: The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) of the publisher of this message.
          type: string
        connectionId:
          description: The connection ID of the publisher of this message.
          type: string
        # TODO: Currently object does not work with application/x-www-form-urlencoded
        extras:
          $ref: '#/components/schemas/Extras'

    Extras:
      type: object
      description: Extras object. Currently only allows for [push](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example) extra.
      properties:
        push:
          $ref: '#/components/schemas/Push'

    Push:
      type: object
      properties:
        data:
          description: Arbitrary [key-value string-to-string payload](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example).
          type: string
        notification:
          $ref: '#/components/schemas/Notification'
        apns:
          description: Extends and overrides generic values when delivering via APNs. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          type: object
          properties:
            notification:
              $ref: '#/components/schemas/Notification'
        fcm:
          description: Extends and overrides generic values when delivering via GCM/FCM. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          type: object
          properties:
            notification:
              $ref: '#/components/schemas/Notification'
        web:
          description: Extends and overrides generic values when delivering via web. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          type: object
          properties:
            notification:
              $ref: '#/components/schemas/Notification'

    Notification:
      type: object
      properties:
        title:
          description: Title to display at the notification.
          type: string
        body:
          description: Text below title on the expanded notification.
          type: string
        icon:
          description: Platform-specific icon for the notification.
          type: string
        sound:
          description: Platform-specific sound for the notification.
          type: string
        collapseKey:
          # Needs more information
          description: Platform-specific, used to group notifications together.
          type: string

    PresenceMessage:
      type: object
      properties:
        id:
          description: Unique ID assigned by Ably to this presence update.
          type: string
          readOnly: true
        action:
          description: The event signified by a PresenceMessage.
          type: string
          enum: [ ABSENT, PRESENT, ENTER, LEAVE, UPDATE ]
          readOnly: true
        data:
          description: The presence update payload, if provided.
          type: string
        clientId:
          description: The client ID of the publisher of this presence update.
          type: string
        connectionId:
          description: The connection ID of the publisher of this presence update.
          type: string
        timestamp:
          description: Timestamp when the presence update was received by Ably, as milliseconds since the epoch.
          type: integer
          format: int64
          readOnly: true
        encoding:
          description: This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload.
          type: string
        extras:
          $ref: '#/components/schemas/Extras'

    TokenRequest:
      type: object
      properties:
        keyName:
          type: string
          description: Name of the key used for the TokenRequest. The keyName comprises of the app ID and key ID on an API Key.
          example: xVLyHw.LMJZxw
        capability:
          type: object
          description: The [capabilities](https://www.ably.io/documentation/core-features/authentication#capabilities-explained) (i.e. a set of channel names/namespaces and, for each, a set of operations) which should be a subset of the set of capabilities associated with the key specified in keyName.
          example: { "channel1": [ "publish", "subscribe" ]}
        clientId:
          type: string
          description: The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) to be assosciated with the token. Can be set to * to allow for any client ID to be used.
        timestamp:
          type: integer
          description: Time of creation of the Ably TokenRequest.
        nonce:
          type: string
          description: An unquoted, un-escaped random string of at least 16 characters. Used to ensure the Ably TokenRequest cannot be reused.
      required:
        - keyName
        - capability
        - timestamp
        - nonce

    SignedTokenRequest:
      allOf:
        - $ref: '#/components/schemas/TokenRequest'
        - type: object
          properties:
            mac:
              type: string
              description: A signature, generated as an HMAC of each of the above components, using the key secret value.
          required:
            - mac

    TokenDetails:
      type: object
      properties:
        token:
          type: string
          description: The Ably Token.
        keyName:
          type: string
          description: Name of the key used to create the token
        issued:
          type: integer
          description: Timestamp of token creation.
        expires:
          type: integer
          description: Timestamp of token expiration.
        capability:
          # TODO: capabilities object representation, does validation as well
          type: string
          description: Regular expression representation of the capabilities of the token.

    ChannelDetails:
      type: object
      properties:
        channelId:
          type: string
          description: The required name of the channel including any qualifier, if any.
        region:
          type: string
          description: In events relating to the activity of a channel in a specific region, this optionally identifies the region.
        isGlobalMaster:
          type: boolean
          description: In events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel.
        status:
          $ref: '#/components/schemas/ChannelStatus'
      required:
        - channelId

    ChannelStatus:
      type: object
      description: A ChannelStatus instance.
      properties:
        isActive:
          type: boolean
          description: A required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
        occupancy:
          $ref: '#/components/schemas/Occupancy'
      required:
        - isActive

    Occupancy:
      type: object
      description: An Occupancy instance indicating the occupancy of a channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
      properties:
        publishers:
          type: integer
          description: The number of connections attached to the channel that are authorised to publish.
        subscribers:
          type: integer
          description: The number of connections attached that are authorised to subscribe to messages.
        presenceSubscribers:
          type: integer
          description: The number of connections that are authorised to subscribe to presence messages.
        presenceConnections:
          type: integer
          description: The number of connections that are authorised to enter members into the presence channel.
        presenceMembers:
          type: integer
          description: The number of members currently entered into the presence channel.

    DeviceDetails:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the device generated by the device itself.
        clientId:
          type: string
          description: Optional trusted client identifier for the device.
        formFactor:
          type: string
          description: Form factor of the push device.
          enum: [ phone, tablet, desktop, tv, watch, car, embedded ]
        metadata:
          type: object
          description: Optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges and will be used more extensively in the future with smart notifications.
        platform:
          type: string
          description: Platform of the push device.
          enum: [ ios, android ]
        deviceSecret:
          type: string
          description: Secret value for the device.
        push.recipient:
          $ref: '#/components/schemas/Recipient'
        push.state:
          type: string
          description: the current state of the push device.
          enum: [ Active, Failing, Failed ]
          readOnly: true

    # Excludes web for now due to not being supported
    Recipient:
      type: object
      description: Push recipient details for a device.
      properties:
        transportType:
          type: string
          description: Defines which push platform is being used.
          enum: [ apns, fcm, gcm ]
        deviceToken:
          type: string
          # TODO: Link to above enum for required
          description: when using APNs, specifies the required device token.
        registrationToken:
          type: string
          # TODO: Link to above enum for required
          description: when using GCM or FCM, specifies the required registration token.
        clientId:
          type: string
          # TODO: Link to no transportType
          description: Client ID of recipient
          writeOnly: true
        deviceId:
          type: string
          # TODO: Link to no transportType
          description: Client ID of recipient
          writeOnly: true

    Error:
      type: object
      description: Returned error from failed REST.
      properties:
        message:
          type: string
          description: Message explaining the error's cause.
        code:
          type: integer
          description: Error code.
        statusCode:
          type: integer
          description: Status error code.
        href:
          type: string
          description: Link to help with error.
        serverId:
          type: string
          description: Server ID with which error was encountered.

  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/x-msgpack:
          schema:
            $ref: '#/components/schemas/Error'
        text/html:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        x-ably-errorcode:
          $ref: '#/components/headers/ErrorCode'
        x-ably-errormessage:
          $ref: '#/components/headers/ErrorMessage'
        x-ably-serverid:
          $ref: '#/components/headers/ServerId'

security:
  - basicAuth: []
  - bearerAuth: []

servers:
- url: https://rest.ably.io

paths:
  /channels/{channel_id}/messages:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: Get message history for a channel
      operationId: getMessagesByChannel
      tags:
        - History
      description: Get message history for a channel
      parameters:
        - $ref: '#/components/parameters/channelId'
        - $ref: '#/components/parameters/filterStart'
        - $ref: '#/components/parameters/filterLimit'
        - $ref: '#/components/parameters/filterEnd'
        - $ref: '#/components/parameters/filterDirection'
      responses:
        '2XX':
          description: OK
          headers:
            link:
              $ref: '#/components/headers/Link'
            x-ably-serverid:
              $ref: '#/components/headers/ServerId'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'
            application/x-msgpack:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'
            text/html:
              schema:
                type: string
        default:
          description: Error
          headers:
            x-ably-errorcode:
              $ref: '#/components/headers/ErrorCode'
            x-ably-errormessage:
              $ref: '#/components/headers/ErrorMessage'
            x-ably-serverid:
              $ref: '#/components/headers/ServerId'

    post:
      summary: Publish a message to a channel
      operationId: publishMessagesToChannel
      description: Publish a message to the specified channel
      tags:
        - Publishing
      parameters:
        - $ref: '#/components/parameters/channelId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/Message'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '2XX':
          description: OK
          headers:
            x-ably-serverid:
              $ref: '#/components/headers/ServerId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  channel:
                    type: string
                  messageId:
                    type: string
            application/x-msgpack:
              schema:
                type: object
                properties:
                  channel:
                    type: string
                  messageId:
                    type: string
            text/html:
              schema:
                type: object
                properties:
                  channel:
                    type: string
                  messageId:
                    type: string
        default:
          $ref: '#/components/responses/Error'

  /channels/{channel_id}/presence:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: Get presence of a channel
      operationId: getPresenceOfChannel
      description: Get presence on a channel
      tags:
        - Status
      parameters:
        - $ref: '#/components/parameters/channelId'
        - name: clientId
          in: query
          schema:
            type: string
        - name: connectionId
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          headers:
            link:
              $ref: '#/components/headers/Link'
            x-ably-serverid:
              $ref: '#/components/headers/ServerId'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PresenceMessage'
            application/x-msgpack:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PresenceMessage'
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Error'

  /channels/{channel_id}/presence/history:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: Get presence history of a channel
      operationId: getPresenceHistoryOfChannel
      description: Get presence on a channel
      tags:
        - History
      parameters:
        - $ref: '#/components/parameters/channelId'
        - $ref: '#/components/parameters/filterStart'
        - $ref: '#/components/parameters/filterLimit'
        - $ref: '#/components/parameters/filterEnd'
        - $ref: '#/components/parameters/filterDirection'
      responses:
        '2XX':
          description: OK
          headers:
            link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PresenceMessage'
            application/x-msgpack:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PresenceMessage'
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Error'

  /channels/{channel_id}:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: Get metadata of a channel
      operationId: getMetadataOfChannel
      description: Get metadata of a channel
      tags:
        - Status
      parameters:
        - $ref: '#/components/parameters/channelId'
      responses:
        '200':
          description: OK
          headers:
            x-ably-serverid:
              $ref: '#/components/headers/ServerId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelDetails'
        default:
          $ref: '#/components/responses/Error'

  /channels:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: Enumerate all active channels of the application
      operationId: getMetadataOfAllChannels
      description: Enumerate all active channels of the application
      tags:
        - Status
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 100
        - in: query
          name: prefix
          schema:
            type: string
          description: Optionally limits the query to only those channels whose name starts with the given prefix
        - in: query
          name: by
          schema:
            type: string
            enum: [ value, id ]
          description: optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value)
      responses:
        '2XX':
          description: OK
          headers:
            link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/ChannelDetails'
                  - type: array
                    items:
                      type: string
            application/x-msgpack:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/ChannelDetails'
                  - type: array
                    items:
                      type: string
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Error'

  /push/deviceRegistrations:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: List devices registered for receiving push notifications
      operationId: getRegisteredPushDevices
      description: List of device details of devices registed for push notifications.
      tags:
        - Push
      parameters:
        - name: deviceId
          description: Optional filter to restrict to devices associated with that deviceId.
          in: query
          schema:
            type: string
        - name: clientId
          in: query
          description: Optional filter to restrict to devices associated with that clientId.
          schema:
            type: string
        - name: limit
          in: query
          description: The maximum number of records to return.
          schema:
            type: integer
            default: 100
            maximum: 1000
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'

    post:
      summary: Register a device for receiving push notifications
      operationId: registerPushDevice
      description: Register a device’s details, including the information necessary to deliver push notifications to it. Requires "push-admin" capability.
      tags:
        - Push
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'

    delete:
      summary: Unregister matching devices for push notifications
      operationId: unregisterAllPushDevices
      description: Unregisters devices. All their subscriptions for receiving push notifications through channels will also be deleted.
      tags:
        - Push
      parameters:
        # TODO: Implement a oneOf filter
        - name: deviceId
          description: Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
          in: query
          schema:
            type: string
        - name: clientId
          in: query
          description: Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.
          schema:
            type: string
      responses:
        '2XX':
          description: OK
        default:
          $ref: '#/components/responses/Error'

  /push/deviceRegistrations/{device_id}:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      operationId: getPushDeviceDetails
      summary: Get a device registration
      description: Get the full details of a device.
      tags:
        - Push
      parameters:
        - $ref: '#/components/parameters/deviceId'
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'

    put:
      summary: Update a device registration
      operationId: putPushDeviceDetails
      description: Device registrations can be upserted (the existing registration is replaced entirely) with a PUT operation. Only clientId, metadata and push.recipient are mutable.
      tags:
        - Push
      parameters:
        - $ref: '#/components/parameters/deviceId'
      requestBody:
        content:
          # TODO: Some application of allOf to enforce usage of all details
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'

    patch:
      summary: Update a device registration
      operationId: patchPushDeviceDetails
      description: Specific attributes of an existing registration can be updated. Only clientId, metadata and push.recipient are mutable.
      tags:
        - Push
      parameters:
        - $ref: '#/components/parameters/deviceId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'

    delete:
      summary: Unregister a single device for push notifications
      operationId: unregisterPushDevice
      description: Unregisters a single device by its device ID. All its subscriptions for receiving push notifications through channels will also be deleted.
      tags:
        - Push
      parameters:
        - $ref: '#/components/parameters/deviceId'
      responses:
        '2XX':
          description: OK
        default:
          $ref: '#/components/responses/Error'

  /push/deviceRegistrations/{device_id}/resetUpdateToken:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: Reset a registered device's update token
      operationId: updatePushDeviceDetails
      description: Gets an updated device details object.
      tags:
        - Push
      parameters:
        - $ref: '#/components/parameters/deviceId'
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'

  /push/channelSubscriptions:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      summary: List channel subscriptions
      operationId: getPushSubscriptionsOnChannels
      description: Get a list of push notification subscriptions to channels.
      tags:
        - Push
      parameters:
        - name: channel
          in: query
          description: Filter to restrict to subscriptions associated with that channel.
          schema:
            type: string
        # TODO: Implement a oneOf filter
        - name: deviceId
          description: Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
          in: query
          schema:
            type: string
        - name: clientId
          in: query
          description: Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.
          schema:
            type: string
        - name: limit
          in: query
          description: The maximum number of records to return.
          schema:
            type: integer
            default: 100
            maximum: 1000
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'

    post:
      summary: Subscribe a device to a channel
      operationId: subscribePushDeviceToChannel
      description: Subscribe either a single device or all devices associated with a client ID to receive push notifications from messages sent to a channel.
      tags:
        - Push
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    channel:
                      type: string
                      description: Channel name.
                    deviceId:
                      type: string
                      description: Must be set when clientId is empty, cannot be used with clientId.
                - type: object
                  properties:
                    channel:
                      type: string
                      description: Channel name.
                    clientId:
                      type: string
                      description: Must be set when deviceId is empty, cannot be used with deviceId.
            example:
              channel: my:channel
              clientId: myClientId
          application/x-msgpack:
            schema:
              oneOf:
                - type: object
                  properties:
                    channel:
                      type: string
                      description: Channel name.
                    deviceId:
                      type: string
                      description: Must be set when clientId is empty, cannot be used with clientId.
                - type: object
                  properties:
                    channel:
                      type: string
                      description: Channel name.
                    clientId:
                      type: string
                      description: Must be set when deviceId is empty, cannot be used with deviceId.
            example:
              channel: my:channel
              clientId: myClientId
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  properties:
                    channel:
                      type: string
                      description: Channel name.
                    deviceId:
                      type: string
                      description: Must be set when clientId is empty, cannot be used with clientId.
                - type: object
                  properties:
                    channel:
                      type: string
                      description: Channel name.
                    clientId:
                      type: string
                      description: Must be set when deviceId is empty, cannot be used with deviceId.
            example:
              channel: my:channel
              clientId: myClientId
      responses:
        '2XX':
          description: OK
        default:
          $ref: '#/components/responses/Error'

    delete:
      summary: Delete a registered device's update token
      operationId: deletePushDeviceDetails
      description: Delete a device details object.
      tags:
        - Push
      parameters:
        - name: channel
          in: query
          description: Filter to restrict to subscriptions associated with that channel.
          schema:
            type: string
        # TODO: Cannot currently use oneOf for below two parameters. If https://github.com/OAI/OpenAPI-Specification/issues/256 is resolved, we should make use of oneOf here.
        - name: deviceId
          description: Must be set when clientId is empty, cannot be used with clientId.
          in: query
          schema:
            type: string
        - name: clientId
          in: query
          description: Must be set when deviceId is empty, cannot be used with deviceId.
          schema:
            type: string
      responses:
        '2XX':
          description: OK
        default:
          $ref: '#/components/responses/Error'

  /push/channels:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'
    get:
      summary: List all channels with at least one subscribed device
      operationId: getChannelsWithPushSubscribers
      description: Returns a paginated response of channel names.
      tags:
        - Push
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
            application/x-msgpack:
              schema:
                type: array
                items:
                  type: string
            text/html:
              schema:
                type: array
                items:
                  type: string
        default:
          $ref: '#/components/responses/Error'

  /push/publish:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    post:
      summary: Publish a push notification to device(s)
      operationId: publishPushNotificationToDevices
      description: A convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their client identifier.
      tags:
        - Push
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient:
                  $ref: '#/components/schemas/Recipient'
                push:
                  $ref: '#/components/schemas/Push'
              required:
                - recipient
          application/x-msgpack:
            schema:
              type: object
              properties:
                recipient:
                  $ref: '#/components/schemas/Recipient'
                push:
                  $ref: '#/components/schemas/Push'
              required:
                - recipient
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                recipient:
                  $ref: '#/components/schemas/Recipient'
                push:
                  $ref: '#/components/schemas/Push'
              required:
                - recipient
      responses:
        '2XX':
          description: OK
        default:
          $ref: '#/components/responses/Error'

  /keys/{keyName}/requestToken:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    # TODO: Allow for no auth for SignedTokenRequest. May not be possible to specify.
    post:
      summary: Request an access token
      operationId: requestAccessToken
      description: This is the means by which clients obtain access tokens to use the service. You can see how to construct an Ably TokenRequest in the [Ably TokenRequest spec](https://www.ably.io/documentation/rest-api/token-request-spec) documentation, although we recommend you use an Ably SDK rather to create a TokenRequest, as the construction of a TokenRequest is complex. The resulting token response object contains the token properties as defined in Ably TokenRequest spec. Authentication is not required if using a Signed TokenRequest.
      tags:
        - Authentication
      parameters:
        - $ref: '#/components/parameters/key_name'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/TokenRequest'
                - $ref: '#/components/schemas/SignedTokenRequest'
            example:
              keyName: "YourKey.Name"
              timestamp: "1559124196551"
              capability:
                channel1: [ "publish", "subscribe" ]
                wildcard:channels:*: [ "publish" ]
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDetails'
            # TODO: Verify no x-www-form-urlencoded
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/TokenDetails'
        default:
          $ref: '#/components/responses/Error'

  /stats:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'
    get:
      summary: Retrieve usage statistics for an application
      operationId: getStats
      description: The Ably system can be queried to obtain usage statistics for a given application, and results are provided aggregated across all channels in use in the application in the specified period. Stats may be used to track usage against account quotas.
      tags:
        - Stats
      parameters:
        - $ref: '#/components/parameters/filterStart'
        - $ref: '#/components/parameters/filterLimit'
        - $ref: '#/components/parameters/filterEnd'
        - $ref: '#/components/parameters/filterDirection'
        - name: unit
          in: query
          description: Specifies the unit of aggregation in the returned results.
          schema:
            type: string
            default: minute
            enum: [ minute, hour, day, month ]

      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                type: object
        default:
          $ref: '#/components/responses/Error'

  /time:
    parameters:
      - $ref: '#/components/parameters/versionHeader'
      - $ref: '#/components/parameters/responseFormat'

    get:
      security: []
      summary: Get the service time
      operationId: getTime
      description: This returns the service time in milliseconds since the epoch.
      tags:
        - Stats
      responses:
        '2XX':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
            application/x-msgpack:
              schema:
                type: array
                items:
                  type: integer
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Error'

# TODO: Better define pagination responses and flow
# TODO: Links for responses meanings