swagger.yaml

# Copyright (C) 2021-2023 Technology Matters
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published
# by the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see https://www.gnu.org/licenses/.

openapi: 3.0.0
servers:
  - url: /
    description: Development server
info:
  description: |
    You can find out more about Swagger at
    [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).
    # Introduction
    This API is documented in **OpenAPI format**. 
    Here we will describe the params of our serverless functions and their return values,
    as well as their required auth methods.
    # Authentication
    <SecurityDefinitions />
  version: 1.0.0
  title: Tech Matters serverless API
  termsOfService: ''
  contact:
    name: Tech Matters
    email:
    url: https://techmatters.org/
  x-logo:
    url: 'https://techmatters.org/wp-content/uploads/2018/12/tech-matters-cropped.png'
    altText: Tech Matters logo
  license:
    name: GPL 3.0
    url: 'https://www.gnu.org/licenses/gpl-3.0.en.html'
externalDocs:
  description: Explore our projects.
  url: 'https://github.com/tech-matters'
tags:
  - name: Functions
    description: Serverless functions served from Twilio
  - name: Assets
    description: Static assets served from Twilio
  # - name: pet_model
  #   x-displayName: The Pet Model
  #   description: |
  #     <SchemaDefinition schemaRef="#/components/schemas/Pet" />
  - name: contact_model
    x-displayName: The contact model
  - name: contact_api
    x-displayName: The contact api endpoints
x-tagGroups:
  - name: Serverless
    tags:
      - Functions
      - Assets
  - name: HRM_models
    x-displayName: HRM-DB Models
    tags:
      - contact_model
  - name: HRM_api
    x-displayName: HRM api endpints
    tags: 
      - contact_api
  # - name: Models
  #   tags:
  #     - pet_model
  #     - store_model
paths:
  /swagger.html:
    get:
      tags:
        - Assets
      summary: API specification in OpenApi 3.0 format
      description: Fetches the html file where the API is described (a.k.a the web you are at right now).
      operationId: swagger
      responses:
        '200': 
          description: successful operation

  /populateCounselors:
    parameters:
    post:
      tags:
        - Functions
      summary: Retrieves councelors (workers) from a given workspace
      description: Given a valid Twilio's workspace Sid [and a helpline optionally] 
        will return the list of asociated workers, or error otherwise. If helpline is provided, the workers
        will be filtered to match it, if not all workers will be sent.
      operationId: populateCounselors
      requestBody:
        description: user info to be filled
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - workspaceSID
              properties:
                workspaceSID:
                  type: string
                  description: SID of the target workspace.
                helpline:
                  type: string
                  description: helpline to add as filter.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  workerSummaries:
                    type: array
                    items:
                      type: object
                      properties:
                        fullName: 
                          type: string
                          description: name of the councelor
                        sid: 
                          type: string
                          description: unique Twilio's identifier for each councelor
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - TwilioJWT:
  /getTranslation:
    parameters:
    post:
      tags:
        - Functions
      summary: Retrieves the translation of flex UI strings for the given language (if pressent)
      description: Given a valid language code, will return the flex UI translations. 
        If the translation is missing, the response will contain an internal error status 500.
      operationId: getTranslation
      requestBody:
        description: user info to be filled
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - language
              properties:
                language:
                  type: string
                  description: lnaguage code that represents the desired translation.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
                description: JSON representation of the strings object.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - TwilioJWT:
  /getMessages:
    parameters:
    post:
      tags:
        - Functions
      summary: Retrieves the translated system strings that are used to send to a chat-type contact.
      description: Given a valid language code, will return the translated strings used to comunicate with the contact. 
        If the translation is missing, the response will contain an internal error status 500.
      operationId: getMessages
      requestBody:
        description: user info to be filled
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - language
              properties:
                language:
                  type: string
                  description: lnaguage code that represents the desired translation.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
                description: JSON representation of the strings object.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - TwilioJWT:
components:
  # schemas:
  #   ApiResponse:
  #     type: object
  #     properties:
  #       code:
  #         type: integer
  #         format: int32
  #       type:
  #         type: string
  #       message:
  #         type: string
  #   Cat:
  #     description: A representation of a cat
  #     allOf:
  #       - $ref: '#/components/schemas/Pet'
  #       - type: object
  #         properties:
  #           huntingSkill:
  #             type: string
  #             description: The measured skill for hunting
  #             default: lazy
  #             example: adventurous
  #             enum:
  #               - clueless
  #               - lazy
  #               - adventurous
  #               - aggressive
  #         required:
  #           - huntingSkill
  #   Category:
  #     type: object
  #     properties:
  #       id:
  #         description: Category ID
  #         allOf:
  #           - $ref: '#/components/schemas/Id'
  #       name:
  #         description: Category name
  #         type: string
  #         minLength: 1
  #       sub:
  #         description: Test Sub Category
  #         type: object
  #         properties:
  #           prop1:
  #             type: string
  #             description: Dumb Property
  #     xml:
  #       name: Category
  #   Dog:
  #     description: A representation of a dog
  #     allOf:
  #       - $ref: '#/components/schemas/Pet'
  #       - type: object
  #         properties:
  #           packSize:
  #             type: integer
  #             format: int32
  #             description: The size of the pack the dog is from
  #             default: 1
  #             minimum: 1
  #         required:
  #           - packSize
  #   HoneyBee:
  #     description: A representation of a honey bee
  #     allOf:
  #       - $ref: '#/components/schemas/Pet'
  #       - type: object
  #         properties:
  #           honeyPerDay:
  #             type: number
  #             description: Average amount of honey produced per day in ounces
  #             example: 3.14
  #             multipleOf: .01
  #         required:
  #           - honeyPerDay
  #   Id:
  #     type: integer
  #     format: int64
  #     readOnly: true
  schemas:
    ErrorString:
      type: string
      description: descriptive message about the error.
    ErrorSchema:
      type: object
      properties:
        message:
          type: string
          description: descriptive message about the error.
        status:
          type: string
          description: status code of the original error (usefull on 5xx errors).
  responses:
    BadRequest:
        description: Bad request or invalid parameters
        content: 
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    UnauthorizedError:
      description: Access token is missing or invalid
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorString'
    InternalError:
        description: Internal Server Error
        content: 
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  securitySchemes:
    TwilioJWT:            # arbitrary name for the security scheme
      description: A valid [Twilio Flex Token](https://www.twilio.com/docs/flex/call-functions-from-plugins#securing-your-twilio-function)
        that is included in the body, [according to this](https://github.com/twilio/twilio-flex-token-validator).
      type: apiKey
      in: body
      name: Token
  # examples:
  #   Order:
  #     value:
  #       quantity: 1,
  #       shipDate: 2018-10-19T16:46:45Z,
  #       status: placed,
  #       complete: false