openapi-spec.yaml

openapi: 3.0.3
info:
  title: Tempsy RESTful API
  description: Temporary Files Storage API Documentation
  version: 0.8.0
  license:
    name: MIT
    url: https://opensource.org/license/mit
  contact:
    name: Afifurrohman
    url: https://www.afifurrohman.my.id
    email: afifurrohman.id@outlook.com
servers:
  - url: https://tempsy.afifurrohman.my.id
    description: Production server
  - url: https://staging.tempsy.afifurrohman.my.id
    description: Staging server
paths:
  /files/{username}:
    get:
      security:
        - bearerAuth: [ ]
      tags:
        - files
      summary: Get all files
      description: Get all files of the user
      parameters:
        - $ref: '#/components/parameters/accept'
        - $ref: '#/components/parameters/username'
        - name: mime_type
          in: query
          description: Filter by file mime type, using like equalization not strict equalization
          required: false
          schema:
            type: string
        - name: name
          in: query
          description: Filter by name, using like equalization not strict equalization
          required: false
          schema:
            type: string
        - name: size
          in: query
          required: false
          description: Filter by file size
          schema:
            type: integer
            format: int64
        - name: limit
          required: false
          in: query
          description: Limit List file
          schema:
            type: integer
            format: int64
              

      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/fileData'
              examples:
                ok:
                  value:
                      - name: hello.txt
                        url: https://storage.googleapis.com/...
                        autoDeleteAt: 1634179200000
                        privateUrlExpires: 100
                        isPublic: false
                        uploadedAt: 1634179200000
                        updatedAt: 1634179200000
                        size: 100
                        mimeType: text/plain; charset=utf-8

                      - name: example.png
                        url: https://tempsy.afifurrohman.my.id/files/afif/public/example.png
                        autoDeleteAt: 1634179200000
                        privateUrlExpires: 100
                        isPublic: true
                        uploadedAt: 1634179200000
                        updatedAt: 1634179200000
                        size: 100
                        mimeType: image/png
        500:
          description: Unknown Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/internalServer'
    post:
      security:
        - bearerAuth: [ ]
      tags:
        - files
      summary: Upload file
      description: Upload file on the server by the user
      parameters:
        - $ref: '#/components/parameters/accept'
        - name: file-name
          in: header
          description: File name of the file want to be uploaded
          required: true
          schema:
            $ref: '#/components/schemas/fileName'

        - $ref: '#/components/parameters/username'
        - $ref: '#/components/parameters/fileMetaAutoDeleteAt'
        - $ref: '#/components/parameters/fileMetaPrivateUrl'
        - $ref: '#/components/parameters/fileMetaPublic'
        - $ref: '#/components/parameters/type'
      requestBody:
        $ref: '#/components/requestBodies/uploadFile'

      responses:
        201:
          description: Success Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fileData'
              examples:
                ok:
                  $ref: '#/components/examples/dataResponse'

        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                invalidFileName:
                  summary: Bad Request invalid file name
                  value:
                    apiError:
                      kind: invalid_file_name
                      description: File name must be alphanumeric and contain extension separated by dot, underscore, or dash
                errorEmptyFileUpload:
                  $ref: '#/components/examples/invalidEmptyFile'
        422:
          description: Unprocessable Entity, Missing Header file metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/missingHeaderMetadata'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  summary: Unsupported Media Type
                  value:
                    apiError:
                      kind: unsupported_content_type
                      description: 'Unsupported Content-Type: application/octet-stream'
        409:
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  summary: File name Conflict
                  value:
                    apiError:
                      kind: file_already_exists
                      description: 'File: hello.txt already exists'
        500:
          description: Unknown Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/internalServer'
    delete:
      security:
        - bearerAuth: []
      tags:
        - files
      summary: Delete all files
      description: Delete all files of the user
      parameters:
        - $ref: '#/components/parameters/accept'
        - $ref: '#/components/parameters/username'
      responses:
        204:
          description: Success
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  summary: Bad Request delete empty files
                  value:
                    apiError:
                      kind: delete_empty_data
                      description: 'Cannot delete empty data files, no data for user: afif'

        500:
          description: Unknown Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/internalServer'
  /files/{username}/public/{filename}:
    get:
      tags:
        - file
      summary: Get public file
      description: Get public file by file name
      parameters:
        - $ref: '#/components/parameters/accept'
        - $ref: '#/components/parameters/username'
        - $ref: '#/components/parameters/filename'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fileData'
              examples:
                ok:
                  $ref: '#/components/examples/dataResponse'
        404:
          description: File Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/fileNotFound'
        500:
          description: Unknown Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/internalServer'
  /files/{username}/{filename}:
    get:
      security:
        - bearerAuth: []
      tags:
        - file
      summary: Get file
      description: Get file by file name
      parameters:
        - $ref: '#/components/parameters/accept'
        - $ref: '#/components/parameters/username'
        - $ref: '#/components/parameters/filename'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fileData'
              examples:
                ok:
                  $ref: '#/components/examples/dataResponse'
        404:
          description: File Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/fileNotFound'
        500:
          description: Unknown Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/internalServer'
    put:
      security:
        - bearerAuth: []
      tags:
        - file
      summary: Update file
      description: Update file by file name
      parameters:
        - $ref: '#/components/parameters/accept'
        - $ref: '#/components/parameters/username'
        - $ref: '#/components/parameters/filename'
        - $ref: '#/components/parameters/fileMetaAutoDeleteAt'
        - $ref: '#/components/parameters/fileMetaPrivateUrl'
        - $ref: '#/components/parameters/fileMetaPublic'
        - $ref: '#/components/parameters/type'
      requestBody:
        $ref: '#/components/requestBodies/uploadFile'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fileData'
              examples:
                ok:
                  $ref: '#/components/examples/dataResponse'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                errorMismatchContentType:
                  summary: Bad Request mismatch content type
                  value:
                    apiError:
                      kind: mismatch_content_type
                      description: Please use the same content type as the original file
                errorUpdateWithEmptyFile:
                  $ref: '#/components/examples/invalidEmptyFile'
        422:
          description: Unprocessable Entity, Missing Header file metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/missingHeaderMetadata'
        404:
          description: File Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/fileNotFound'
        500:
          description: Unknown Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/internalServer'
    delete:
      security:
        - bearerAuth: []
      tags:
        - file
      summary: Delete file
      description: Delete file by file name
      parameters:
        - $ref: '#/components/parameters/accept'
        - $ref: '#/components/parameters/username'
        - $ref: '#/components/parameters/filename'
      responses:
        204:
          description: Success
        404:
          description: File Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/fileNotFound'
        500:
          description: Unknown Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              examples:
                error:
                  $ref: '#/components/examples/internalServer'

  /auth/userinfo/me:
    get:
      security:
        - bearerAuth: []
      tags:
        - auth
      summary: Get user info
      description: Return total files and username
      parameters:
        - $ref: '#/components/parameters/accept'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: api data userinfo
                properties:
                  username:
                    type: string
                    description: Username of the user
                    example: afif
                  totalFiles:
                    type: string
                    description: Email of the user
                    example: 100

              examples:
                ok:
                  value:
                      username: afif
                      totalFiles: 100
        400:
            description: Bad Request
            content:
                application/json:
                  schema:
                      $ref: '#/components/schemas/errorResponse'
                  examples:
                      error:
                        summary: Bad Request invalid token
                        description: Invalid Token cause by authorization header have invalid token, maybe expires or have been revoked
                        value:
                          apiError:
                              kind: invalid_token
                              description: Invalid Token, cannot get user info

        500:
            description: Unknown Internal Server Error
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/errorResponse'
                    examples:
                        error:
                          $ref: '#/components/examples/internalServer'
  /auth/guest/token:
    get:
      tags:
        - auth
      summary: Get guest token
      description: return guest token
      parameters:
        - $ref: '#/components/parameters/accept'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: api data guest token
                properties:
                  accessToken:
                    type: string
                    description: Guest token
                  expiresIn:
                    type: integer
                    description: Token expires in seconds
                    example: 3600

        400:
            description: Bad Request
            content:
                application/json:
                  schema:
                      $ref: '#/components/schemas/errorResponse'
                  examples:
                      error:
                        summary: Bad Request already have token
                        description: Already have a token
                        value:
                          apiError:
                              kind: already_have_token
                              description: You already have token
        500:
            description: Unknown Internal Server Error
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/errorResponse'
                    examples:
                        error:
                          $ref: '#/components/examples/internalServer'


components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Google OAuth2 access_token or Guest JWT access_token

  parameters:
    fileMetaPublic:
      name: file-is-public
      in: header
      description: File is public or not
      required: true
      schema:
        type: boolean
    fileMetaPrivateUrl:
      name: file-private-url-expires
      required: true
      in: header
      description: Private url will be expires
      schema:
        description: Seconds, relative from now, Must be positive integer
        type: integer
        maximum: 604800 # 7 days
        minimum: 2
        format: int
    fileMetaAutoDeleteAt:
      name: file-auto-delete-at
      in: header
      description: File will be delete at, max is one year since now
      required: true
      schema:
        type: integer
        format: int64
        description: Unix date in milliseconds

    username:
      name: username
      in: path
      description: Username of the user
      required: true
      schema:
        type: string
    filename:
      name: filename
      in: path
      description: File name of the file
      required: true
      schema:
        type: string
        format: name.ext
    accept:
      name: accept
      required: true
      in: header
      description: Accept Content-Type must be application/json if you want this response api
      schema:
        type: string
        description: Accepted Content-Type by client
        enum: 
          - application/json
          - application/json; charset=utf-8
    type:
      name: content-type
      required: true
      in: header
      description: Content-Type Header for file upload
      schema:
        type: string
        description: Content-Type accepted by the server
        enum:
          - application/json; charset=utf-8
          - application/json
          - text/html; charset=utf-8
          - text/html
          - text/plain; charset=utf-8
          - text/plain
          - text/javascript; charset=utf-8
          - text/javascript
          - application/xml; charset=utf-8
          - application/xml
          - text/csv
          - text/css
          - image/gif
          - image/jpeg
          - image/png
          - application/x-sh
          - image/svg+xml
          - image/webp
          - image/x-icon # Major Browsers
          - image/vnd.microsoft.icon # Standard IANA
          - image/avif
          - application/wasm

  schemas:
    fileName:
      description: File name pattern of the file
      type: string
      pattern: ^[a-zA-Z0-9_-]+\.+[a-zA-Z0-9_-]+$
      example: example.txt
    errorResponse:
      description: Error Response body, without data
      type: object
      properties:
        apiError: 
          type: object
          properties:
            kind:
              type: string
              description: Error type
              example: invalid_file_name
            description:
              type: string
              description: Error description
              example: File name must be alphanumeric and contain extension separated by dot, underscore, or dash
    fileData:
      description: File Data Response
      type: object
      properties:
        name:
          $ref: '#/components/schemas/fileName'
        url:
          type: string
          format: uri
          example: https://tempsy.afifurrohman.my.id/files/afif/public/hello.txt
        autoDeleteAt:
          type: integer
          format: int64
          description: Unix date in milliseconds
        privateUrlExpires:
          type: integer
          format: int
          description: Seconds, relative from now
        isPublic:
          type: boolean
          description: File is public or not
        uploadedAt:
          type: integer
          format: int64
          description: Unix date in milliseconds
        updatedAt:
          type: integer
          format: int64
          description: Unix date in milliseconds
        size:
          type: integer
          format: int64
          description: File size in bytes
        mimeType:
          type: string
          description: MIME type of file, IANA Standard
          example: text/plain; charset=utf-8
  examples:
    fileNotFound:
      summary: File Not Found
      description: File Not Found Error Response
      value:
        apiError:
          kind: file_not_found
          description: 'File: hello.txt not found'
    missingHeaderMetadata:
      summary: Missing Header Metadata
      description: Error Missing file metadata
      value:
        apiError:
          kind: invalid_header_file
          description: Cannot Parse NaN as int64
    dataResponse:
      summary: Data Response Body
      description: Single File Data for Response Body
      value:
        name: hello.webp
        url: https://storage.googleapis.com/...
        autoDeleteAt: 1634179200000
        privateUrlExpires: 100
        isPublic: false
        uploadedAt: 1634179200000
        updatedAt: 1634179200000
        size: 100
        mimeType: text/plain; charset=utf-8
    internalServer:
      summary: Internal Server Error
      description: Internal Server Error for Response Body
      value:
        apiError:
          kind: unknown_server_error
          description: Unknown Internal Server Error. Unexpected Error
    invalidEmptyFile:
      summary: Invalid Empty File
      description: Invalid Empty File Upload Error Response
      value:
        apiError:
          kind: invalid_empty_file
          description: File cannot be empty
  requestBodies:
    uploadFile:
      required: true
      description: Binary or text file
      content:
        application/json:
          schema:
            nullable: false
            description: JSON
            type: string
          examples:
            json:
              value:
                message: Hello World
        image/png:
          schema:
            nullable: false
            description: Image binary
            type: string
            format: binary
        image/jpeg:
          schema:
            nullable: false
            description: Image binary
            type: string
            format: binary
        text/html:
          schema:
            nullable: false
            description: Html Text
            type: string
        text/plain:
          schema:
            nullable: false
            description: Plain Text
            type: string
          examples:
            text:
              value: Hello World

        text/javascript:
          schema:
            nullable: false
            description: Javascript Text
            type: string
          examples:
            js:
              value: |
                console.info('Hello World')

        application/xml:
          schema:
            nullable: false
            description: XML Text
            type: string

        text/csv:
          schema:
            nullable: false
            description: CSV Text
            type: string
        text/css:
          schema:
            nullable: false
            description: CSS Text
            type: string
        image/gif:
            schema:
                nullable: false
                description: GIF Image
                type: string
                format: binary
        application/x-sh:
            schema:
                nullable: false
                description: Shell Script text
                type: string
            examples:
                sh:
                    value: |
                        #!/bin/sh
                        echo "Hello World"

        image/svg+xml:
            schema:
                nullable: false
                description: SVG Image text
                type: string
        image/webp:
            schema:
                nullable: false
                description: WebP Image
                type: string
                format: binary
        image/vnd.microsoft.icon:
            schema:
                nullable: false
                description: Icon Image
                type: string
                format: binary
        image/avif:
            schema:
                nullable: false
                description: AVIF Image
                type: string
                format: binary

        application/wasm:
            schema:
                nullable: false
                description: WebAssembly Binary
                type: string
                format: binary