openapi: 3.0.1
info:
  title: Events Subscriptions API
  description: >-
    ## Introduction

    Welcome to the Aritma Events API!


    Over time there will be introduced changes to the API as we continuously
    introduce improvements. You have the option to use a specific version or the
    most recent version, supported versions are available in the response header
    api-supported-versions.

    Use a specific version of the API by specifying the api-version header, for
    example api-version: 1.0. If you don't specify the header, the latest
    version will be used.

    If a version has been scheduled to be removed, it will be reported through
    the api-supported-versions header.



    Our API uses resource-oriented endpoint paths, accepts
    [Json-Encoded](https://www.json.org/json-en.html) request bodies, returns
    [Json-Encoded](https://www.json.org/json-en.html) responses, and uses
    standard HTTP response codes and verbs.
  contact:
    name: Aritma
    url: https://aritma.com/general-inquiry/
  version: v1
servers:
  - url: https://events.dev.aritma.io
    description: Subscriptions API Dev
  - url: https://events.aritma.io
    description: Subscriptions API
paths:
  /api/failed-events:
    get:
      tags:
        - Deadletter
      summary: Gets a list of deadletters for a container.
      parameters:
        - name: subscriptionName
          in: query
          description: If specified restricts result to a specific subscription.
          schema:
            type: string
        - name: pageSize
          in: query
          description: Divides the result into pages. (Default = 10, max = 100, min = 1)
          schema:
            type: integer
            format: int32
            default: 10
        - name: cursor
          in: query
          description: Reference for next page.
          schema:
            type: integer
            format: int64
        - name: fromDate
          in: query
          description: >-
            If specified restricts result to a time period newer than this
            value.
          schema:
            type: string
            format: date-time
        - name: toDate
          in: query
          description: >-
            If specified restricts result to a time period older than this
            value.
          schema:
            type: string
            format: date-time
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FailedEventPage'
            application/json:
              schema:
                $ref: '#/components/schemas/FailedEventPage'
            text/json:
              schema:
                $ref: '#/components/schemas/FailedEventPage'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/failed-events/{eventId}:
    get:
      tags:
        - Deadletter
      summary: Downloads a failed event.
      parameters:
        - name: eventId
          in: path
          description: The unique event id.
          required: true
          schema:
            type: string
            format: uuid
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/FailedEventDto'
            application/json:
              schema:
                $ref: '#/components/schemas/FailedEventDto'
            text/json:
              schema:
                $ref: '#/components/schemas/FailedEventDto'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
        - Deadletter
      summary: Deletes a failed event.
      parameters:
        - name: eventId
          in: path
          description: The unique event id.
          required: true
          schema:
            type: string
            format: uuid
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Creates a new subscription.
      description: "<br>Create a subscription for a set of event-types.\r\n<br>To complete provisioning of the subscription you must do a `GET` request against the `validationUrl` sent to the `Delivery.Url`.\r\n<br>Webhooks of the specified event-types will be delivered when provisioning has succeeded."
      parameters:
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      requestBody:
        description: >-
          Aritma.Events.Subscription.Api.Models.Requests.CreateSubscriptionRequest
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '201':
          description: Created
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags:
        - Subscriptions
      summary: Gets all subscriptions available.
      parameters:
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/subscriptions/{subscriptionName}:
    get:
      tags:
        - Subscriptions
      summary: Gets a subscription matching the id specified.
      operationId: GetSubscription
      parameters:
        - name: subscriptionName
          in: path
          description: The unique name of the subscription.
          required: true
          schema:
            type: string
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
        - Subscriptions
      summary: Updates an existing subscription matching the id specified.
      description: "<br>Updates a subscription for a set of event-types.\r\n<br>To complete provisioning of the subscription you must do a `GET` request against the `validationUrl` sent to the `Delivery.Url`.\r\n<br>Webhooks of the specified event-types will be delivered when provisioning has succeeded."
      parameters:
        - name: subscriptionName
          in: path
          description: The unique identifier of a subscription.
          required: true
          schema:
            type: string
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      requestBody:
        description: >-
          A
          Aritma.Events.Subscription.Api.Models.Requests.UpdateSubscriptionRequest
          object used to Update a subscription.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/EventSubscriptionStateDto'
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscriptionStateDto'
            text/json:
              schema:
                $ref: '#/components/schemas/EventSubscriptionStateDto'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
        - Subscriptions
      summary: Deletes an existing subscription matching the id specified.
      parameters:
        - name: subscriptionName
          in: path
          description: The unique name of a subscription.
          required: true
          schema:
            type: string
        - name: ResourceUri
          in: header
          description: ResourceUri to create the event subscriptions under.
          schema:
            type: string
        - name: TenantId
          in: header
          description: TenantId used by the customer.
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    CreateSubscriptionRequest:
      type: object
      properties:
        name:
          type: string
          description: A unique identifier for the subscription.
          nullable: true
          example: ExampleName
        events:
          type: array
          items:
            type: string
          description: List of events to subscribe to.
          nullable: true
        delivery:
          $ref: '#/components/schemas/Delivery'
        expirationTime:
          type: string
          description: A date and time for when the subscription should expire.
          format: date-time
          nullable: true
          example: '2024-01-01T00:00:00.000Z'
        retryPolicy:
          $ref: '#/components/schemas/RetryPolicy'
        deadletterEnabled:
          type: boolean
          description: >-
            A boolean describing if failed events should be stored in a
            container.
          nullable: true
          example: true
      additionalProperties: false
      description: An object used to create a new subscription.
    Delivery:
      type: object
      properties:
        url:
          type: string
          description: An url to the webhook that should receive the events.
          nullable: true
          example: https://localhost.test
        maxEventsPerBatch:
          type: integer
          description: Max number of events to be sent in a single batch.
          format: int32
          nullable: true
          example: 10
        preferredBatchSizeInKiloBytes:
          type: integer
          description: preferred size in kilo bytes, of the batches to be sent.
          format: int32
          nullable: true
          example: 128
        authorizationHeader:
          type: string
          description: >-
            Authorization header that will be included in all webhook
            deliveries.
          nullable: true
          example: Bearer mF_9.B5f-4.1JqM
      additionalProperties: false
      description: An object used to configure event delivery properties.
    EventSubscriptionStateDto:
      type: object
      properties:
        provisioningState:
          type: string
          nullable: true
      additionalProperties: false
    FailedEventDataDto:
      type: object
      properties:
        deadletterId:
          type: string
          description: The id of the deadletter.
          nullable: true
        subscriptionName:
          type: string
          description: The name of the subcription the event was sent to.
          nullable: true
        topic:
          type: string
          description: The topic this deadletter belongs to.
          nullable: true
        createdOn:
          type: string
          description: When the deadletter was created.
          format: date-time
        sizeInBytes:
          type: integer
          description: The size of the deadletter file.
          format: int64
      additionalProperties: false
    FailedEventDto:
      type: object
      properties:
        id:
          type: string
          nullable: true
        eventTime:
          type: string
          format: date-time
        subject:
          type: string
          nullable: true
        eventType:
          type: string
          nullable: true
        deliveryAttempts:
          type: integer
          format: int32
        lastHttpStatusCode:
          type: integer
          format: int32
        lastDeliveryOutcome:
          type: string
          nullable: true
        publishTime:
          type: string
          format: date-time
        lastDeliveryAttemptTime:
          type: string
          format: date-time
        failureReason:
          type: string
          nullable: true
        data:
          nullable: true
      additionalProperties: false
    FailedEventPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FailedEventDataDto'
          description: A list of failed events.
          nullable: true
        pageSize:
          type: integer
          description: The max number of items per page.
          format: int32
        cursor:
          type: integer
          description: A reference for the next page.
          format: int64
          nullable: true
      additionalProperties: false
      description: >-
        Object for paging
        Aritma.Events.SubscriptionManagement.Dto.FailedEventDataDto
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    RetryPolicy:
      type: object
      properties:
        ttl:
          type: string
          description: A period for the events to be retried if they fail
          example: '00:10:00'
        maxEventDeliveryAttempts:
          type: integer
          description: Max number of retries for a event if it fails.
          format: int32
          example: 30
      additionalProperties: false
      description: An object used to configure the retry policy for the subscription.
    SubscriptionResponse:
      type: object
      properties:
        name:
          type: string
          description: A unique identifier for the subscription.
          nullable: true
          example: ExampleName
        eventTypes:
          type: array
          items:
            type: string
          description: List of events to subscribe to.
          nullable: true
        delivery:
          $ref: '#/components/schemas/Delivery'
        expirationDate:
          type: string
          description: A date and time for when the subscription should expire.
          format: date-time
          nullable: true
          example: 05/29/2024 05:50:06
        retryPolicy:
          $ref: '#/components/schemas/RetryPolicy'
        deadletterEnabled:
          type: boolean
          description: >-
            A boolean describing if failed events should be stored in a
            container.
          example: true
        provisioningState:
          type: string
          description: "<br>An event status describing the status for the subscription.\r\n<br>Ok - the subscription is active and operating.\r\n<br>Pending - the subscription is awaiting webhook validation from user.\r\n<br>Processing - the subscription is applying changes, will change status to Ok when done.\r\n<br>Aborted - the last changes was either canceled or failed."
          nullable: true
          example: Ok
      additionalProperties: false
      description: An object describing the subscription and its properties.
    UpdateSubscriptionRequest:
      type: object
      properties:
        events:
          type: array
          items:
            type: string
          description: List of events to subscribe to.
          nullable: true
        delivery:
          $ref: '#/components/schemas/Delivery'
        expirationTime:
          type: string
          description: A date and time for when the subscription should expire.
          format: date-time
          nullable: true
          example: '2024-01-01T00:00:00.000Z'
        retryPolicy:
          $ref: '#/components/schemas/RetryPolicy'
        deadletterEnabled:
          type: boolean
          description: >-
            A boolean describing if failed events should be stored in a
            container.
          nullable: true
          example: true
      additionalProperties: false
      description: An object used to update an existing subscription.
  securitySchemes:
    authorization_code_dev:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://id-dev.zdata.no/connect/authorize
          tokenUrl: https://id-dev.zdata.no/connect/token
          scopes:
            api: Access to Event Subscription Api
    client_credentials_dev:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://id-dev.zdata.no/connect/token
          scopes:
            api: Access to Event Subscription Api
    authorization_code:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://id.zdata.no/connect/authorize
          tokenUrl: https://id.zdata.no/connect/token
          scopes:
            api: Access to Event Subscription Api
    client_credentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://id.zdata.no/connect/token
          scopes:
            api: Access to Event Subscription Api
security:
  - authorization_code_dev:
      - api
  - client_credentials_dev:
      - api
  - authorization_code:
      - api
  - client_credentials:
      - api
