openapi: 3.2.0
info:
  title: Tapis Notifications Events API
  description: The Tapis Notifications API provides for management of subscriptions and event publication
  version: 26Q1.1
  termsOfService: https://tapis-project.org
  contact:
    name: Notifications API - CICSupport
    url: https://tapis-project.org
    email: cicsupport@tacc.utexas.edu
  license:
    name: 3-Clause BSD License
    url: https://opensource.org/licenses/BSD-3-Clause
servers:
- url: http://localhost:8080/
  description: Local test environment
  variables: {}
- url: https://dev.develop.tapis.io/
  description: Development environment
  variables: {}
tags:
- name: Events
  description: Event publication
paths:
  /v3/notifications/events/publish:
    post:
      tags:
      - Events
      description: Publish an event to be distributed to all subscribers.
      operationId: publishEvent
      security:
      - TapisJWT: []
      parameters:
      - name: tenant
        in: query
        description: Highly restricted. Tenant associated with the event. Only services may set the tenant. By default, oboTenant from the JWT is used.
        schema:
          type: string
      requestBody:
        required: true
        description: A JSON object specifying the event details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Event published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '400':
          description: Input error. Invalid JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '401':
          description: Not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
      summary: Publish event
      x-summary-source: derived
  /v3/notifications/events:
    post:
      tags:
      - Events
      description: '(**DEPRECATED** Please use endpoint *notifications/events/publishEvent*)


        Post an event to be distributed to all subscribers. Only services may post events.


        The attributes *source*, *type* and *timestamp* are required. Note that certain attributes, marked as

        *attribute* in the list below, are allowed but ignored. These attributes are maintained by Tapis. They are

        present when the event is part of a delivered notification.


        Event attributes:

        - source: Context in which event happened: Examples: *Jobs*, *Systems*.

        - type: Type of event. Used for routing notifications. A series of 3 fields separated by the dot character. Pattern is *service.category.detail*. Examples: *jobs.new_status.complete*, *systems.system.create*, *files.object.delete*

        - subject: Subject of event in the context of the service. Examples: job Id, system Id, file path, role name, etc.

        - timestamp: When the event happened.

        - data: Optional additional information associated with the event. Data specific to the service associated with the event.

        - deleteSubscriptionsMatchingSubject: Boolean indicating that all subscriptions whose *subjectFilter* matches the *subject* of the event should be deleted once all notifications are delivered.

        - seriesId: Optional Id that may be used to group events from the same tenant, source and subject. In a series, event order is preserved when sending out notifications.

        - *tenant*: Tapis tenant associated with the event.

        - *uuid*: Tapis generated unique identifier.

        - *user*: Tapis user associated with the event.


        Note that events are not persisted by the front end api service. When received they are simply sent to a

        message broker. The back end dispatch service will persist events temporarily in order to support recovery.


        An event is delivered to the delivery target in a Notification object. Notification attributes:

        - uuid: Unique identifier for the notification.

        - subscriptionName: Name of subscription associated with the event.

        - event: All information contained in the event.

        - eventUuid: Unique identifier for the event.

        - tenant: tenant associated with the event.

        - deliveryTarget: the delivery target

        - created: When the notification was created.


        For details on the schema for a Notification object, please see the request body specification included under

        the endpoint for *recordTestNotification*, at path */v3/notifications/test/callback/{name}*


        Note that certain attributes in the request body (such as tenant) are allowed but ignored. These attributes

        are maintained by Tapis. They are present when the event is part of a delivered notification.

        The attributes that are allowed but ignored are


        - tenant

        - uuid

        - user'
      operationId: postEvent
      security:
      - TapisJWT: []
      deprecated: true
      parameters:
      - name: tenant
        in: query
        description: Highly restricted. Tenant associated with the event. Only services may set the tenant. By default, oboTenant from the JWT is used.
        schema:
          type: string
      requestBody:
        required: true
        description: A JSON object specifying the event details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Event posted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '400':
          description: Input error. Invalid JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '401':
          description: Not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
      summary: Post event
      x-summary-source: derived
  /v3/notifications/events/endSeries:
    post:
      tags:
      - Events
      description: 'End an event series. Series tracking data will be deleted. A subsequent new event published with the same

        tenant, source, subject and seriesId will create a new series with the *seriesSeqCount* starting at 1.

        Associated event source, subject and seriesId must be provided in the request body.


        To specify a tenant other than the oboTenant, please use the query parameter *tenant*.'
      operationId: endEventSeries
      security:
      - TapisJWT: []
      parameters:
      - name: tenant
        in: query
        description: Highly restricted. Tenant associated with the event. Only services may set the tenant. By default, oboTenant from the JWT is used.
        schema:
          type: string
      requestBody:
        required: true
        description: A JSON object specifying the event series to be ended.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSeries'
      responses:
        '200':
          description: Event series ended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '400':
          description: Input error. Invalid JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '401':
          description: Not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespBasic'
      summary: End event series
      x-summary-source: derived
components:
  schemas:
    Event:
      type: object
      required:
      - source
      - type
      - timestamp
      properties:
        source:
          type: string
        type:
          type: string
        subject:
          type: string
        data:
          type: string
        seriesId:
          type: string
        endSeries:
          type: boolean
          default: false
        timestamp:
          type: string
        deleteSubscriptionsMatchingSubject:
          type: boolean
          default: false
        tenant:
          type: string
        user:
          type: string
        uuid:
          type: string
        received:
          type: string
        seriesSeqCount:
          type: integer
    EventSeries:
      type: object
      required:
      - source
      - subject
      - seriesId
      properties:
        source:
          type: string
          minLength: 1
        subject:
          type: string
          minLength: 1
        seriesId:
          type: string
          minLength: 1
    RespBasic:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        result:
          type: object
        metadata:
          type: object
  securitySchemes:
    TapisJWT:
      type: apiKey
      description: Tapis signed JWT token authentication
      name: X-Tapis-Token
      in: header
externalDocs:
  description: Tapis Project
  url: https://tapis-project.org