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: |
            Not Found. This occurs when the specified user is not listed under the trial.
        '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: |
            Created: the request has been processed and the user has been registered for the trial.
          schema:
            $ref: '#/definitions/Subscription'
        '202':
          description: |
            Accepted: the request has been received, but the user may not yet be subscribed to the trial.
            The server will process the request asynchronously.
            Resubmitting the same request may result in a `409 Conflict` error.
        '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.

      When a user subscribes a trial, the subscription is in the `SUBSCRIBED` state
      If the user wants to unsubscribe, the state changes to `UNSUBSCRIBED`.
      When the trial is going to be activated (by the Trial Manager, the owner of the trial), then the state of the
      selected `SUBSCRIBED` users becomes `ACTIVE`.
      The Trial Manager can change the state of any user, within its own subscription,
      to any state (e.g. can disable a subscription setting the state to `DISABLED`).
    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'