documentation.yaml

openapi: 3.0.0
info:
  version: "1.0.0"
  title: 'Gami API Specification'
  description: | 
    Default auth token for testing environments are: \'admin_token\', \'user_token\' and \'another_user_token\'.
    All listing endpoints support \'itemsPerPage\', \'page\' and time based search filters.
paths:
  /identifierCreate:
    post:
      tags:
        - Identifier
      description: Create identifiers. Please take a look at IdentifierLogic!
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Identifier'
                  example:
                    - key: "https://gamiworld.com/share/testkey"
                      behavior: "RANDOMIZER"
                      logic: "{\"assocCollections\": [1, 2, 3]"

      responses:
        '200':
          description: Created objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Identifier'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'

  /identifierList:
    post:
      tags:
        - Identifier
      description: List multiple identifiers using search filters. For time based searching take a look at TimeSearchFilter schema.
      requestBody:
        required: True
        content: 
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    query:
                      type: array
                      items:
                        $ref: '#/components/schemas/Identifier'
                      example:
                        - key: "https://gamiworld.com/share/testkey"
                        - id: 1
      responses:
        '200':
          description: Found objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/Identifier'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'
          
  /identifierModify:
    post:
      tags:
        - Identifier
      description: Modify identifiers selected by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                      update:
                        $ref: '#/components/schemas/Identifier'
                  example:
                    - id: 1
                      update:
                        behavior: "SINGLE"
                    
      responses:
        '200':
          description: Modified objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Identifier'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'      

  /identifierDelete:
    post:
      tags:
        - Identifier
      description: Delete identifiers selected by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    
      responses:
        '200':
          description: Just ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'      

  /identifierRead:
    post:
      tags:
        - Identifier
      description: Return associated collections of multiple identifiers based on their internal logic.
      requestBody:
        required: True
        content: 
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    query:
                      type: array
                      items:
                        $ref: '#/components/schemas/Identifier'
                      example:
                        - key: "https://gamiworld.com/share/testkey"
      responses:
        '200':
          description: Referenced collection(s)
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      type: integer

        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'

  /collectionCreate:
    post:
      tags:
        - Collection
      description: Create collection. You can add an array of modules when creating a collection, look at the example.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Collection'
            example:
              data:
                title: "test"
                accessStatus: "PUBLIC"
                protectionType: "IGNORED"
                modules:
                  - type: "TEXT"
                    text: "this is some sample text"
                  - type: "TEXT"
                    text: "another sample text"
                  - type: "CONTACT"
                    emails: "{}"
      
      responses:
        '200':
          description: Created object
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    $ref: '#/components/schemas/Collection'

        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'

  /collectionList:
    post:
      tags:
        - Collection
      description: List multiple collections using search filters. For time based searching take a look at TimeSearchFilter schema.
      requestBody:
        required: True
        content: 
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    query:
                      $ref: '#/components/schemas/Collection'
            example:
              data:
                query:
                  itemsPerPage: 2
                  page: 0
                  id: 1
      responses:
        '200':
          description: Found objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Collection'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'  
  /collectionModify:
    post:
      tags:
        - Collection
      description: Modify collection selected by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: integer
                    update:
                      $ref: '#/components/schemas/Collection'
            example:
              data:
                id: 1
                update:
                  title: "updated title"
                    
      responses:
        '200':
          description: Modified object
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    $ref: '#/components/schemas/Collection'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'      

  /collectionDelete:
    post:
      tags:
        - Collection
      description: Delete collections selected by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: integer
            example:
              data:
                id: 1
                    
      responses:
        '200':
          description: Just ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string         
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'      

  /moduleCreate:
    post:
      tags:
        - Module
      description: Create one or more modules. You MUST specify the concrete type. Concrete type fields can be included in the same object with other fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    allOf:
                      - $ref: '#/components/schemas/Module'
                      - $ref: '#/components/schemas/ModuleImage'
                      - $ref: '#/components/schemas/ModuleVideo'
                      - $ref: '#/components/schemas/ModuleList'
                      - $ref: '#/components/schemas/ModuleText'
                      - $ref: '#/components/schemas/ModuleContact'
            example:
              data:
                - CollectionId: 1
                  type: "TEXT"
                  text: "this is some sample text"
      
      responses:
        '200':
          description: Created object
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Module'

        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'

  /moduleList:
    post:
      tags:
        - Module
      description: List multiple modules using search filters. For time based searching take a look at TimeSearchFilter schema.
      requestBody:
        required: True
        content: 
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    query:
                      allOf:
                        - $ref: '#/components/schemas/Module'
                        - $ref: '#/components/schemas/ModuleImage'
                        - $ref: '#/components/schemas/ModuleVideo'
                        - $ref: '#/components/schemas/ModuleList'
                        - $ref: '#/components/schemas/ModuleText'
                        - $ref: '#/components/schemas/ModuleContact'
            example:
              data:
                query:
                  CollectionId: 1
      responses:
        '200':
          description: Found objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Module'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'  

  /moduleModify:
    post:
      tags:
        - Module
      description: Modify module selected by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: integer
                    update:
                      allOf:
                        - $ref: '#/components/schemas/Module'
                        - $ref: '#/components/schemas/ModuleImage'
                        - $ref: '#/components/schemas/ModuleVideo'
                        - $ref: '#/components/schemas/ModuleList'
                        - $ref: '#/components/schemas/ModuleText'
                        - $ref: '#/components/schemas/ModuleContact'
            example:
              data:
                id: 1
                update:
                  text: "This text was updated"
                    
      responses:
        '200':
          description: Modified object
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    $ref: '#/components/schemas/Module'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError'      

  /moduleDelete:
    post:
      tags:
        - Module
      description: Delete modules selected by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: integer
            example:
              data:
                id: 1
                    
      responses:
        '200':
          description: Just ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /moduleDisplay:
    post:
      tags:
        - Module
      description: Display module by id. An access code or a password may be needed. Concrete type fields will be contained in a sub-object named like the concrete type class. Ex. ModuleText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    query:
                      type: object
                      properties:
                        id: 
                          type: integer
            example:
              data:
                query:
                  id: 1
                    
      responses:
        '200':
          description: Found module.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    $ref: '#/components/schemas/Module'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 
  
  /moduleAssociate:
    post:
      tags:
        - Module
      description: Associate a module with a collection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    ModuleId:
                      type: integer
                    CollectionId:
                      type: integer
            example:
              data:
                ModuleId: 1
                CollectionId: 1
                    
      responses:
        '200':
          description: Just ok.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 
  
  /moduleDeassociate:
    post:
      tags:
        - Module
      description: Deassociate a module from its parent collection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    ModuleId:
                      type: integer
            example:
              data:
                ModuleId: 1
                    
      responses:
        '200':
          description: Just ok.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /fileUpload:
    post:
      tags:
        - File
      description: |
        To upload a file you must do a request to this route with the type and filename specified. 
        The server will return a Google Storage Signed URL. 
        Do a POST request to the Signed URL to start the upload transaction and the use PUT requests to the URL returned in the Location header to upload the file. 
        Read the according specification on Google Storage API website. After uploading, the file will be added to the processing queue.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - video
                        - image
                        - text
                    filename:
                      type: string
            example:
              data:
                type: "text"
                filename: "test"
                    
      responses:
        '200':
          description: Google Storage Signed URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: object
                    properties:
                      url:
                        type: string
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /fileDownload:
    post:
      tags:
        - File
      description: Similar to uploading, do a request with the type and filename and you will receive a Google Storage Signed URL for downloading the file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - video
                        - image
                        - text
                    filename:
                      type: string
            example:
              data:
                type: "text"
                filename: "test"
                    
      responses:
        '200':
          description: Google Storage Signed URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: object
                    properties:
                      url:
                        type: string
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /fileList:
    post:
      tags:
        - File
      description: Searching file metadata.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    query:
                      type: array
                      items:
                        $ref: '#/components/schemas/FileInfo'
            example:
              data:
                query:
                  - filename: "test"
                    
      responses:
        '200':
          description: Found files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileInfo'
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /fileStaus:
    post:
      tags:
        - File
      description: Check processing status of a file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    filename:
                      type: string
            example:
              data:
                filename: "test"
                    
      responses:
        '200':
          description: The processing status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - NOT_PROCESSED
                          - IN_QUEUE
                          - PROCESSED
                          - ORIGINAL
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /fileDelete:
    post:
      tags:
        - File
      description: Mark a file as deleted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    filename:
                      type: string
            example:
              data:
                filename: "test"
                    
      responses:
        '200':
          description: Just ok.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    
        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /fileAssociate:
    post:
      tags:
        - File
      description: Associate a file with a module.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    filename:
                      type: string
                    ModuleId:
                      type: string
            example:
              data:
                filename: "test"
                ModuleId: 1
                    
      responses:
        '200':
          description: Just ok.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string

        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

  /fileDeassociate:
    post:
      tags:
        - File
      description: Deassociate a file from its parent module.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    filename:
                      type: string
            example:
              data:
                filename: "test"
                    
      responses:
        '200':
          description: Just ok.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string

        '400':
          $ref: '#/components/responses/ServerError'
        '403':
          $ref: '#/components/responses/AuthError' 

components:
  responses:
    AuthError:
      description: Insufficient permissions or invalid token
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                description: Error cause.
                type: string
                
    ServerError:
      description: Empty query/empty body or processing error like using invalid arguments.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                description: Error cause.
                type: string

  securitySchemes:
    TokenAuth:
      description: Each user is identified by a token with certain permissions.
      type: apiKey
      in: header       
      name: token

    AccessCodeAuth:
      description: Some collections could be protected by an access code or password. You can provide it in this header.
      type: apiKey
      in: header
      name: code

  schemas:
    Identifier:
      description: An identifier references one or more collections using a custom logic.
      type: object
      required:
        - key
        - behavior
        - logic
      properties:
        id:
          type: integer
        key:
          type: string
        parentToken:
          type: string
        behavior:
          type: string
          enum:
            - RANDOMIZER
            - CYCLIC
            - SINGLE
            - CHRONO
            - RESERVED
        logic:
          $ref: '#/components/schemas/IdentifierLogic'
        updatedByToken:
          type: string
        deletedByToken:
          type: string
          
    IdentifierLogic:
      description: This should be serialized as a STRING. Don\'t send it as an object.
      type: object
      required:
        - assocCollections
      properties:
        assocCollections:
          type: array
          items:
            type: integer
            
    TimeSearchFilter:
      description: This describes how to search objects based on create/update/delete times. Add an object like this in any search query.
      type: object
      required:
        - alterationTypeName
      properties:
        alterationTypeName:
          description: This can be named \'updatedAt\', \'createdAt\' or \'deletedAt\'
          type: object
          properties:
            startTime:
              description: Standard Javascript Datetime format
              type: string
            endTime:
              description: Standard Javascript Datetime format
              type: string
    
    # TODO: collection definition is incomplete. Fix
    Collection:
      description: A collection has multiple modules.
      type: object
      required:
        - title
        - accessStatus
      properties:
        title:
          type: string
        summary:
          type: string
        thumbnail:
          description: Thumbnail filename
          type: string # TODO: this will be changed
        accessStatus:
          type: string
          enum:
            - PUBLIC
            - PRIVATE
        protectionType:
          description: Used only if accessStatus is PRIVATE
          type: string
          enum:
            - PASSWORD
            - ACCESS_CODE
        password:
          description: Used only if protectionType is PASSWORD
          type: string
        accessConfiguration:
          description: Additional configuration if protectionType is ACCESS_CODE
          type: string
        moduleCount:
          type: integer
          default: 0
        inactive:
          type: boolean
          default: false

    Module:
      description: |
        Building blocks of a Collection. Generic structure for multiple types of data.
        Modules are very diverse and the data types that they need to keep isn't uniform.
        To solve this problem, there is a generic table named Module. Each Module entry holds a field
        that describes its type and has a foreign key to a so named 'concrete module entry'. 
        Each concrete module type has its own table. For example there is a ModuleContact for storing contact informations.
        After sending a query to get a specific module, you want to access its concrete fields. To do this, you will find
        in a sub-object with the same name as the concrete module type. For example to access the concrete data of a Module object named 
        'moduleTest' of type CONTACT, you'll do like this 'moduleText.ModuleContact.<specific-field>'.
      type: object
      required:
        - CollectionId
        - type
      properties:
        id:
          type: integer
        CollectionId:
          description: Parent collection id.
          type: integer
        index:
          description: Internal index inside the parent collection.
          type: integer
        type:
          description: Concrete module type.
          type: string
          enum:
            - IMAGE
            - VIDEO
            - LIST
            - TEXT
            - CONTACT
        parentToken:
          type: string
        updatedByToken:
          type: string
        deletedByToken:
          type: string
        inactive:
          type: boolean
        createdAt:
          type: string
        updatedAt:
          type: string
        deletedAt:
          type: string
    
    ModuleVideo:
      type: object
      description: Concrete module for storing videos.
      properties:
        ModuleId:
          description: Parent module id.
          type: integer

    ModuleImage:
      type: object
      description: Concrete module for storing images.
      properties:
        ModuleId:
          description: Parent module id.
          type: integer

    ModuleList:
      type: object
      description: Concrete module for storing a list of links.
      properties:
        ModuleId:
          description: Parent module id.
          type: integer
        icon:
          description: Icon filename
          type: string
        info:
          description: Short description
          type: string
        links:
          description: Array of links, JSON string
          type: string

    ModuleText:
      type: object
      description: Concrete module for storing text data.
      properties:
        ModuleId:
          description: Parent module id.
          type: integer
        text:
          description: Array of objects containing text and their font, size and other stylings. The clinet should decide the format. JSON string.
          type: string

    ModuleContact:
      type: object
      description: Concrete module for storing contact information.
      properties:
        ModuleId:
          description: Parent module id.
          type: integer
        emails:
          description: Object, each key stores an email. JSON string
          type: string
        phoneNumbers:
          description: Object, each key stores a phone number. JSON string
          type: string
        addresses:
          description: Object, each key stores an address. JSON string
          type: string

    FileInfo:
      type: object
      description: Database entry for uploaded files.
      properties:
        id:
          type: integer
        isOriginal:
          description: True if this is the entry of the original uploaded file, not processed.
          type: boolean
        bucket:
          description: Name of the bucket where the file is stored.
          type: string
        path:
          description: Path name in the bucket.
          type: string
        filename:
          description: Generated filename. (uuidv4)
          type: string
        originalFilename:
          description: The original filename.
          type: string
        extension:
          description: Extension of the file format.
          type: string
        sizeInBytes:
          description: Size of the file, in bytes.
          type: integer
        resolutionInPixels:
          description: Resolution in pixels, only one relevant dimension. (720p for example)
          type: integer
        orientation:
          description: Orientation, relevant only for photos. 
          type: string
          enum:
            - LANDSCAPE
            - PORTRAIT
        timeDuration:
          description: Duration in seconds, relevant only for videos.
          type: integer
        FPS:
          description: Frames per second.
          type: integer
        processingRanking:
          description: Ranking used to determine the suited VM instance for processing. UNUSED at the moment.
          type: integer
        estimatedProcessingTimeInMinutes:
          description: Estimated processing time. UNUSED at the moment.
          type: integer
        status:
          type: string
          enum:
            - NOT_PROCESSED
            - IN_QUEUE
            - PROCESSED
            - ORIGINAL
        parentToken:
          type: string
        signedURL:
          description: Cached signed URL for download.
          type: string
        isSignedURLValid:
          description: True if the singed URL is true. TODO this should be removed, is not relevant
          type: string
        deleted:
          description: True if the file was marked as deleted.
          type: string
        deletedByToken:
          type: string
        deletedAt:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string        

security:
  - TokenAuth: []
  - AccessCodeAuth: []

tags:
  - name: Identifier
    description: Identifier CRUD operations. Notice that some of the routes take as input or return ids. Ids are in general a single integer, but they can be an array of integers too (to specify multiple elements).
  - name: Collection
    description: Collection CRUD operations.
  - name: Module
    description: Module CRUD operations. Please take a look at the different module types schemas.
  - name: File
    description: Endpoints for managing files.

servers:
  - description: Deployment API
    url: https://us-central1-gamibackend.cloudfunctions.net/