V1_Spaces.yml

swagger: '2.0'
info:
  x-copyright: 'Copyright IBM Corp. 2017'
  title: Spaces
  description: "Send a message to a space."
  version: 1.0.0
host: api.watsonwork.ibm.com
schemes:
  - https
definitions:
  Message:
    type: object
    description: "Entity that will be passed to spaces' message API."
    required:
      - version
      - annotations
    properties:
      version:
        type: integer
        description: "Version of the message."
      type:
        type: string
        description: The type of message being sent in. At the moment this must be set to "appMessage"
        enum:
          - appMessage
      annotations:
        type: array
        description: "For appMessage, provide array with a single annotation entry of type:generic."
        items:
          $ref: '#/definitions/GenericAnnotation'
  GenericAnnotation:
    type: object
    required:
     - text
    properties:
      id:
        type: string
        description: "Generated or provided id for the saved annotation."
      created:
        type: string
        description: "[Autogenerated] Date and time when annotation was created, in format: yyyy-MM-dd'T'HH:mm:ss.SSSZ"
        readOnly: true
      createdBy:
        type: string
        description: "[Autogenerated] Id of the creator of the annotation."
        readOnly: true
      type:
        type: string
        default: "generic"
        enum:
          - generic
      version:
        type: integer
        description: "Version of the annotation."
      color:
        type: string
        description: "Color of the annotation border."
      title:
        type: string
        description: "Title of the annotation. Supports a subset of markdown."
      text:
        type: string
        description: "Body of text to send inside of the message annotation. Supports a subset of markdown."
      actor:
        type: object
        description: "External user referenced in annotation as actor, owner or author."
        properties:
          name:
            type: string
            description: "Name of the actor defined in the annotation."
  BaseResponse:
    type: object
    description: "Base set of attributes that are autogenerated and appended to a given response."
    properties:
      id:
        type: string
        description: "Generated or provided id for the message."
      created:
        type: string
        description: "Date and time when message was created, in format: yyyy-MM-dd'T'HH:mm:ss.SSSZ"
      createdBy:
        type: string
        description: "Id of the creator of the message."
  Response:
    type: object
    description: "Complete response entity resulting from successful API call."
    allOf:
    - $ref: '#/definitions/BaseResponse'
    - $ref: '#/definitions/Message'
  Error:
    type: object
    description: "Response entity resulting from failed API call."
    properties:
      timestamp:
        type: string
        description: "The time at which the error occurred."
      status:
        type: string
        description: "The HTTP response code."
      error:
        type: string
        description: "The HTTP response message."
      message:
        type: string
        description: "Service defined description of error."
      path:
        type: string
        description: "The HTTP request path."
parameters:
  Authorization:
    name: Authorization
    in: header
    type: string
    description: "Authorization header, in form of `Bearer {access_token}`"
    required: true
responses:
  BadRequest:
    description: "Improperly formed message body."
    schema:
      $ref: '#/definitions/Error'
  Unauthorized:
    description: "Unauthorized."
    schema:
      $ref: '#/definitions/Error'
  Forbidden:
    description: "Forbidden."
    schema:
      $ref: '#/definitions/Error'
  InternalServerError:
    description: "Internal server error."
    schema:
      $ref: '#/definitions/Error'
paths:
  '/v1/spaces/{spaceId}/messages':
    post:
      summary: Send message to a space.
      description: Send a message to a given space by id.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/Authorization'
        - name: body
          in: body
          description: The message entity to be sent.
          required: true
          schema:
            $ref: '#/definitions/Message'
        - name: spaceId
          in: path
          type: string
          description: The space id to send a message to.
          required: true
      responses:
        '201':
          description: "Message was sent successfully."
          schema:
            $ref: '#/definitions/Response'
        '400':
          $ref: '#/responses/BadRequest'
        '401':
          $ref: '#/responses/Unauthorized'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'