api_backend.yaml

swagger: "2.0"
info:
  version: 1.0.0
  title: AGID forms
  description: AGID forms.
host: localhost
basePath: /api/v1
paths:

  "/user/profile":
    get:
      summary: Get user's profile
      description: Returns the profile for the authenticated user.
      responses:
        "200":
          description: Found.
          schema:
            $ref: "#/definitions/UserProfile"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/ProblemJson"
        "401":
          description: Bearer token null or expired.
        "500":
          description: There was an error in retrieving the user profile.
          schema:
            $ref: "#/definitions/ProblemJson"

  "/auth/ipa/token/{ipa_code}":
    post:
      summary: Send an email with a secret code to the RTD.
      description: |
        Send an email with a secret code to the RTD of the Public Administration
        (organization) identified by the IPA code.
        Gets the information on the organization from the
        [IPA](https://indicepa.gov.it) catalogue using the provided IPA code.
        The secret code will be used by the client to login into the backend.
      responses:
        "200":
          description: Organization found.
          schema:
            "$ref": "#/definitions/GetPaFromIpa"
        "400":
          description: Bad request.
          schema:
            $ref: "#/definitions/ProblemJson"
        "404":
          description: No organization found for the provided IPA code.
          schema:
            $ref: "#/definitions/ProblemJson"
        "500":
          description: There was an error retrieving the organization.
          schema:
            $ref: "#/definitions/ProblemJson"
      parameters:
        - name: ipa_code
          in: path
          description: PA IPA code.
          type: string
          required: true

  "/auth/ipa/session/{ipa_code}":
    post:
      summary: Get a bearer token to use with subsequent API calls.
      description: |
        The client post a secret code and the IPA code of the Public Administration
        he wants to personify. If the secret is valid for the provided IPA code,
        then the backend returns a bearer token to authenicate subsequent API calls.
      responses:
        "200":
          description: Authorized.
          schema:
            "$ref": "#/definitions/LoginTokens"
        "400":
          description: Bad request.
          schema:
            $ref: "#/definitions/ProblemJson"
        "401":
          description: Not authorized.
          schema:
            $ref: "#/definitions/ProblemJson"
        "404":
          description: No organization found for the provided IPA code.
          schema:
            $ref: "#/definitions/ProblemJson"
        "500":
          description: There was an error retrieving the organization.
          schema:
            $ref: "#/definitions/ProblemJson"
      parameters:
        - name: ipa_code
          in: path
          description: PA IPA code.
          type: string
          required: true
        - name: body
          in: body
          schema:
            $ref: "#/definitions/LoginCredentials"
          required: true

  ######################

  "/auth/email/token":
    post:
      summary: Send an email with a secret code to the email address provided.
      description: |
        Send an email with a secret code to the email address provided in input.
        The secret code will be used by the client to login into the backend.
      responses:
        "200":
          description: Found.
          schema:
            "$ref": "#/definitions/EmailPayload"
        "400":
          description: Bad request.
          schema:
            $ref: "#/definitions/ProblemJson"
        "500":
          description: Generic error processing the request.
          schema:
            $ref: "#/definitions/ProblemJson"
      parameters:
        - name: body
          in: body
          description: Email address.
          schema:
            $ref: "#/definitions/EmailPayload"
          required: true

  "/auth/email/session":
    post:
      summary: Get a bearer token to use with subsequent API calls.
      description: |
        The client post a secret code and the email address the secret code was sent to.
        If the secret is valid for the provided email address,
        then the backend returns a bearer token to authenicate subsequent API calls.
      responses:
        "200":
          description: Authorized.
          schema:
            "$ref": "#/definitions/LoginTokens"
        "400":
          description: Bad request.
          schema:
            $ref: "#/definitions/ProblemJson"
        "401":
          description: Not authorized.
          schema:
            $ref: "#/definitions/ProblemJson"
        "500":
          description: Generic error processing the request.
          schema:
            $ref: "#/definitions/ProblemJson"
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/EmailLoginCredentials"
          required: true

  ######################

  "/auth/logout":
    post:
      summary: Terminate user session.
      description: |
        Delete the session identified by the provided bearer token.
      responses:
        "200":
          description: Logged out.
          schema:
            "$ref": "#/definitions/SuccessResponse"
        "500":
          description: There was an error deleting user's session.
          schema:
            $ref: "#/definitions/ProblemJson"

schemes:
  - https

security:
  - Bearer: []

definitions:
  HttpStatusCode:
    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
  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:
        $ref: "#/definitions/HttpStatusCode"
      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.
  GetPaFromIpa_ipa_pa:
    type: object
    properties:
      comune:
        type: string
      provincia:
        type: string
      regione:
        type: string
      des_amm:
        type: string
        description: "PA description."
      cod_amm:
        type: string
        description: "IPA code."
      tipologia_istat:
        type: string
        description: "Tipology."
      mail2:
        type: string
        description: "Email address"
    required:
      - comune
      - provincia
      - regione
      - des_amm
      - cod_amm
      - tipologia_istat
  GetPaFromIpa_ipa_ou:
    type: object
    properties:
      cod_ou:
        type: string
      nome_resp:
        type: string
      cogn_resp:
        type: string
      mail_resp:
        type: string
    required:
      - cod_ou
      - nome_resp
      - cogn_resp
      - mail_resp
  GetPaFromIpa:
    type: object
    properties:
      ipa_pa:
        $ref: "#/definitions/GetPaFromIpa_ipa_pa"
      ipa_ou:
        $ref: "#/definitions/GetPaFromIpa_ipa_ou"
    required:
      - ipa_ou
      - ipa_pa
  EmailPayload:
    type: object
    properties:
      email:
        type: string
        format: email
    required:
      - email
  LoginTokens:
    type: object
    properties:
      backend_token:
        type: string
      graphql_token:
        type: string
    required:
      - backend_token
      - graphql_token
  LoginCredentials:
    type: object
    properties:
      secret:
        type: string
    required:
      - secret
  EmailLoginCredentials:
    type: object
    properties:
      email:
        type: string
        format: email
      secret:
        type: string
    required:
      - email
      - secret
  SuccessResponse:
    type: object
    properties:
      message:
        type: string
  UUIDString:
    type: string
    pattern: "^\\\\w+-\\\\w+-\\\\w+-\\\\w+-\\\\w+$"
    # x-import: italia-ts-commons/lib/UUIDString
  UserProfile:
    type: object
    properties:
      email:
        type: string
        format: EmailString
        x-import: italia-ts-commons/lib/strings
      id:
        $ref: "#/definitions/UUIDString"
    required:
      - id
      - email