api_trial_system.yaml

swagger: '2.0'
info:
  version: 13.39.4
  title: Trial System API
host: localhost
basePath: /api/v1
schemes:
  - https
security:
  - Bearer: []
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
paths:
  /trials/{trialId}/subscriptions:
    parameters:
      - $ref: '#/parameters/pathTrialId'
    get:
      operationId: getSubscription
      summary: Get subscription detail
      description: >-
        Returns the details about the subscription of the authenticated user for
        the specified trial.
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/Subscription'
        '401':
          description: Authorization error.
        '404':
          description: Resource not found.
        '429':
          description: Too may requests.
        '500':
          description: There was an error.
          schema:
            $ref: '#/definitions/ProblemJson'
    post:
      operationId: createSubscription
      summary: Create a subscription
      description: Subscribe the authenticated user to the given trial.
      responses:
        '201':
          description: Success.
          schema:
            $ref: '#/definitions/Subscription'
        '202':
          description: >-
            The request has been accepted for processing, but the processing has
            not been completed.
        '400':
          description: Validation error.
          schema:
            $ref: '#/definitions/ProblemJson'
        '401':
          description: Authorization error.
        '409':
          description: The resource already exists.
        '429':
          description: Too may requests.
        '500':
          description: There was an error.
          schema:
            $ref: '#/definitions/ProblemJson'
parameters:
  pathTrialId:
    name: trialId
    in: path
    required: true
    type: string
    minLength: 1
definitions:
  ProblemJson:
    type: object
    properties:
      type:
        type: string
        format: uri
        description: |-
          An absolute URI that identifies the problem type. When dereferenced,
          it SHOULD provide human-readable documentation for the problem type
          (e.g., using HTML).
        default: about:blank
        example: https://example.com/problem/constraint-violation
      title:
        type: string
        description: |-
          A short, summary of the problem type. Written in english and readable
          for engineers (usually not suited for non technical stakeholders and
          not localized); example: Service Unavailable
      status:
        type: integer
        format: int32
        description: >-
          The HTTP status code generated by the origin server for this
          occurrence of the problem.
        minimum: 100
        maximum: 600
        exclusiveMaximum: true
        example: 200
      detail:
        type: string
        description: |-
          A human readable explanation specific to this occurrence of the
          problem.
        example: There was an error processing the request
      instance:
        type: string
        format: uri
        description: >-
          An absolute URI that identifies the specific occurrence of the
          problem.

          It may or may not yield further information if dereferenced.
  CreatedAt:
    type: string
    format: UTCISODateFromString
    description: A date-time field in ISO-8601 format and UTC timezone.
    x-import: '@pagopa/ts-commons/lib/dates'
    example: '2018-10-13T00:00:00.000Z'
  SubscriptionState:
    type: string
    description: |-
      - UNSUBSCRIBED: The user is not subscribed to the specified trial and does
          not have any access to the specified trial.
      - SUBSCRIBED: The user is subscribed to the specified trial and does
          not have any access to the specified trial. The system is going to
          activate the user if any slot for the trial is available.
      - ACTIVE: The user has the access to the specified trial.
      - DISABLED: The user does not have the access to the specified trial.
    enum:
      - UNSUBSCRIBED
      - SUBSCRIBED
      - ACTIVE
      - DISABLED
  TrialId:
    type: string
    description: Unique identifier of the trial.
    minLength: 1
  Subscription:
    type: object
    required:
      - trialId
      - state
      - createdAt
    properties:
      trialId:
        $ref: '#/definitions/TrialId'
      state:
        $ref: '#/definitions/SubscriptionState'
      createdAt:
        $ref: '#/definitions/CreatedAt'