OpenAPI.yaml

openapi: 3.0.0
info:
  title: App Tracker API
  version: 1.0.0

servers:
  - url: http://127.0.0.1:8080
    description: Local development server
  - url: http://apptracker.sg.butanediol.me
    description: Test server

components:
  schemas:
    Error:
      type: object
      properties:
        reason:
          type: string
    
    Designer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        token:
          type: string
        createdAt:
          type: number
          format: double
          description: Milliseconds since 1970 with microsecond precision
          example: 1699486183123.456
    
    DesignerRegister:
      type: object
      required:
        - email
        - password
        - name
      properties:
        email:
          type: string
          format: email
          description: Designer's email address
        name:
          type: string
          description: Designer's name
        password:
          type: string
          minLength: 8
          description: Password must be at least 8 characters long
    
    IconPackVersion:
      type: object
      properties:
        id:
          type: string
          format: uuid
        versionString:
          type: string
        token:
          type: string
    
    IconPackVersionCreate:
      type: object
      required:
        - versionString
        - expireAt
      properties:
        versionString:
          type: string
        expireAt:
          type: number
          format: double
          description: Milliseconds since 1970 with microsecond precision
          example: 1699486183123.456
    
    AppInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        packageName:
          type: string
        mainActivity:
          type: string
        localizedNames:
          type: array
          items:
            type: object
            properties:
              languageCode:
                type: string
              name:
                type: string
              isPrimary:
                type: boolean
              createdAt:
                type: number
                format: double
                description: Milliseconds since 1970 with microsecond precision
              updatedAt:
                type: number
                format: double
                description: Milliseconds since 1970 with microsecond precision
    
    AppInfoCreate:
      type: object
      required:
        - defaultName
        - localizedName
        - languageCode
        - packageName
        - mainActivity
      properties:
        defaultName:
          type: string
        localizedName:
          type: string
        languageCode:
          type: string
        packageName:
          type: string
        mainActivity:
          type: string

    IconUploadRequest:
      type: object
      required:
        - packageName
      properties:
        packageName:
          type: string
          description: Package name of the app to upload icon for

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

tags:
  - name: Designer
    description: Designer authentication and management
  - name: IconPackVersion
    description: Icon pack version management
  - name: AppInfo
    description: App information management
  - name: AppIcon
    description: App icon management
  - name: RequestRecord
    description: Request record management

paths:
  /designer/register:
    post:
      tags:
        - Designer
      summary: Register a new designer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DesignerRegister'
      responses:
        '200':
          description: Successfully registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Designer'
  
  /designer/login:
    get:
      tags:
        - Designer
      summary: Login as designer
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully logged in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Designer'
  
  /icon-pack-version/create:
    post:
      tags:
        - IconPackVersion
      summary: Create a new icon pack version
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IconPackVersionCreate'
      responses:
        '200':
          description: Successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IconPackVersion'
  
  /app-info/search:
    get:
      tags:
        - AppInfo
      summary: Search app info
      parameters:
        - in: query
          name: byName
          schema:
            type: string
        - in: query
          name: byPackageName
          schema:
            type: string
        - in: query
          name: byMainActivity
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: per
          schema:
            type: integer
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppInfo'
                  metadata:
                    type: object
                    properties:
                      page:
                        type: integer
                      per:
                        type: integer
                      total:
                        type: integer
  
  /app-info/create:
    post:
      tags:
        - AppInfo
      summary: Create or update app info
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AppInfoCreate'
      responses:
        '200':
          description: Successfully created/updated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppInfo'

  /app-icon:
    get:
      tags:
        - AppIcon
      summary: Get an app icon redirect URL
      parameters:
        - in: query
          name: packageName
          required: true
          schema:
            type: string
          description: Package name of the app to get icon for
      responses:
        '302':
          description: Redirect to the signed icon URL
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  
  /app-icon/generate-upload-url:
    get:
      tags:
        - AppIcon
      summary: Generate a pre-signed URL for uploading an app icon
      parameters:
        - in: query
          name: packageName
          required: true
          schema:
            type: string
          description: Package name of the app to get icon for
      responses:
        '200':
          description: Successfully generated upload URL
          content:
            application/json:
              schema:
                type: string
                format: uri
        '404':
          description: App not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /icon-pack-version/{iconPackVersionId}/requests:
    get:
      tags:
        - IconPackVersion
      summary: Get requests for a specific icon pack version
      description: Returns requests for an icon pack version. Requires designer authentication and ownership of the icon pack version.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: iconPackVersionId
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the icon pack version to get requests for
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: per
          schema:
            type: integer
      responses:
        '200':
          description: List of requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        appInfo:
                          $ref: '#/components/schemas/AppInfo'
                        createdAt:
                          type: number
                          format: double
                          description: Milliseconds since 1970 with microsecond precision
                  metadata:
                    type: object
                    properties:
                      page:
                        type: integer
                      per:
                        type: integer
                      total:
                        type: integer
        '403':
          description: Designer does not own this icon pack version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Icon pack version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /request-record/{requestRecordId}:
    delete:
      tags:
        - RequestRecord
      summary: Delete a request record
      description: Deletes a request record. Requires designer authentication and ownership of the associated icon pack version.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: requestRecordId
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the request record to delete
      responses:
        '200':
          description: Request record successfully deleted
        '403':
          description: Designer does not own the associated icon pack version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Request record not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'