marketplace_api.yaml

openapi: 3.0.0
info:
  version: "2.0.0"
  title: "Marketplace API"
tags:
  - name: Item
  - name: User
paths:
  /items:
    post:
      tags:
        - Item
      summary: Add a new marketplace item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MarketplaceItem"
      responses:
        201:
          description: Return item id if created successfully
          content:
            text/plain:
              schema:
                type: string
        405:
          $ref: "#/components/responses/InvalidInput"
    get:
      tags:
        - Item
      summary: List marketplace items
      parameters:
        - in: query
          name: author
          schema:
            type: string
        - in: query
          name: name
          schema:
            type: string
        - in: query
          name: category
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MarketplaceItem"

  /items/{itemId}:
    parameters:
      - name: itemId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Item
      summary: Get specific marketplace item info
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketplaceItem"
        404:
          $ref: "#/components/responses/404NotFound"
    put:
      tags:
        - Item
      summary: Update a marketplace item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MarketplaceItem"
      responses:
        200:
          description: OK
        404:
          $ref: "#/components/responses/404NotFound"
        405:
          $ref: "#/components/responses/InvalidInput"
    delete:
      tags:
        - Item
      summary: delete a marketplace item
      responses:
        200:
          description: OK
        404:
          $ref: "#/components/responses/404NotFound"
  /items/{itemId}/description:
    parameters:
      - name: itemId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Item
      responses:
        200:
          description: OK
          content:
            text/plain:
              schema:
                type: string
        404:
          $ref: "#/components/responses/404NotFound"
    put:
      tags:
        - Item
      summary: Update a marketplace item description
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        200:
          description: OK
        404:
          $ref: "#/components/responses/404NotFound"
        405:
          $ref: "#/components/responses/InvalidInput"

  /items/{itemId}/status:
    parameters:
      - name: itemId
        in: path
        required: true
        schema:
          type: string
    put:
      tags:
        - Item
      summary: Update a marketplace item status (approved or rejected)
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        200:
          description: OK
        404:
          $ref: "#/components/responses/404NotFound"
        405:
          $ref: "#/components/responses/InvalidInput"

  /items/{itemId}/submits:
    parameters:
      - name: itemId
        in: path
        required: true
        schema:
          type: string
    put:
      tags:
        - Item
      summary: Increase submits of a marketplace item
      responses:
        200:
          description: OK
        404:
          $ref: "#/components/responses/404NotFound"

  /items/{itemId}/starUsers:
    get:
      tags:
        - Item
      summary: Get star users of specific marketplace item
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        404:
          $ref: "#/components/responses/404NotFound"

  /users:
    post:
      tags:
        - User
      summary: Add a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        201:
          description: Return item id if created successfully
          content:
            text/plain:
              schema:
                type: string
        405:
          $ref: "#/components/responses/InvalidInput"
    get:
      tags:
        - User
      summary: List users
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

  /users/{username}/starItems:
    get:
      tags:
        - User
      summary: list star items of a specific user
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MarketplaceItem"
        404:
          $ref: "#/components/responses/404NotFound"
  /users/{username}/starItems/{itemId}:
    parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: itemId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - User
      summary: Get the stared marketplace item info of a user, 404 if user not stared
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketplaceItem"
        404:
          $ref: "#/components/responses/404NotFound"
    put:
      tags:
        - User
      summary: Star the marketplace item, 409 if already stared
      responses:
        200:
          description: OK
        409:
          description: Conflict
    delete:
      tags:
        - User
      summary: Unstar the item if stared, 404 if not stared
      responses:
        200:
          description: OK
        404:
          $ref: "#/components/responses/404NotFound"
  /storages/blobs:
    get:
      tags:
        - Storage
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [blob]
        - name: storageAccount
          in: query
          schema:
            type: string
        - name: containerName
          in: query
          schema:
            type: string
        - name: user
          in: query
          schema:
            type: string
      responses:
        200:
          description: Get blob storage matches query
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Storage"
    post:
      tags:
        - Storage
      summary: Add a new blob storage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              $ref: "#/components/schemas/Storage"
      responses:
        201:
          description: Return storage id if created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
        400:
          description: Database vlidation error
          content:
            text/plain:
              schema:
                type: string
  /storages/blobs/{blobId}:
    parameters:
      - name: blobId
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Storage
      summary: Get the blob storage of the specified id, 404 if not found
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Storage"
        404:
          description: Not Found
          content:
            text/plain:
              schema:
                type: string
    put:
      tags:
        - Storage
      summary: Update the blob storage of the specified id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Storage"
      responses:
        200:
          description: Updated successfully
          content:
            text/plain:
              schema:
                type: string
        404:
          description: Blob not found
          content:
            text/plain:
              schema:
                type: string
    delete:
      tags:
        - Storage
      summary: Delete the blob storage of the specified id.
      responses:
        200:
          description: Deleted successfully
          content:
            text/plain:
              schema:
                type: string
        404:
          description: Blob not found
          content:
            text/plain:
              schema:
                type: string

components:
  schemas:
    MarketplaceItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        author:
          type: string
        type:
          type: string
        categories:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: "date-time"
        updatedAt:
          type: string
          format: "date-time"
        summary:
          type: string
        description:
          type: string
        content:
          oneOf:
            - $ref: "#/components/schemas/Data"
            - $ref: "#/components/schemas/Docker"
            - $ref: "#/components/schemas/Model"
            - $ref: "#/components/schemas/Job"
        useNumber:
          type: number
        starNumber:
          type: number
        status:
          type: string
          description: pending, approved or rejected
    Storage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum: [blob]
        storageAccount:
          type: string
        containerName:
          type: string
        connectionStrings:
          type: array
          items:
            type: string
        tokens:
          type: array
          items:
            type: string
        users:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: "date-time"
        updatedAt:
          type: string
          format: "date-time"
      required:
        - type
        - storageAccount
        - containerName
        - connectionStrings
    Data:
      type: object
      properties:
        type:
          type: string
          description: public or platform
        content:
          oneOf:
            - $ref: "#/components/schemas/PlatformStorage"
            - $ref: "#/components/schemas/PublicStorage"
    PlatformStorage:
      type: object
      properties:
        storageName:
          type: string
        type:
          type: string
          description: pai storage type, nfs or azure blob
        group:
          type: string
    PublicStorage:
        type: object
        properties:
          url:
            type: string
          processScript:
            type: string
    Docker:
      type: object
      description: TODO
      properties:
        todo:
          type: string
    Model:
      type: object
      description: TODO
      properties:
        todo:
          type: string
    Job:
      type: object
      properties:
        config:
          type: string
    User:
      type: object
      properties:
        name:
          type: string
        groups:
          type: array
          items:
            type: string

  responses:
    404NotFound:
      description: The specified resource was not found.
    InvalidInput:
      description: Invalid input