api.yaml

---
openapi: 3.0.3
info:
  title: MiniCloud API
  description: ""
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers: [ ]
tags:
  - name: server group
    description: Operations about the server groups
  - name: server
    description: Operations about the servers
  - name: template
    description: Operations about the server templates
  - name: system
    description: Operations about the system
paths:
  "/api/v1/group":
    get:
      summary: Get all server groups
      operationId: getGroups
      tags:
        - server group
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ServerGroup"
    post:
      summary: Create a new server group
      operationId: createGroup
      tags:
        - server group
      requestBody:
        description: Create a new server group
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServerGroup"
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerGroup"
        "400":
          description: Invalid input
        "409":
          description: Server group already exists
  "/api/v1/group/{name}":
    get:
      summary: Get the server group
      operationId: getGroup
      parameters:
        - name: name
          in: path
          description: Name of the server group
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server group
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerGroup"
        "400":
          description: Invalid input
        "404":
          description: Server group not found
    delete:
      summary: Delete an existing server group
      operationId: removeGroup
      parameters:
        - name: name
          in: path
          description: Name of the server group
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server group
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid input
        "404":
          description: Server group not found
  "/api/v1/group/{group}/servers":
    get:
      summary: Get all servers of the group
      operationId: getServersInGroup
      parameters:
        - name: group
          in: path
          description: Name of the server group
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server group
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerList"
        "400":
          description: Invalid input
        "404":
          description: Server group not found
  "/api/v1/server":
    get:
      summary: Get all servers
      operationId: getServers
      tags:
        - server
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerList"
    post:
      summary: Create a new server
      operationId: createServer
      tags:
        - server
      requestBody:
        description: Create a new server
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  $ref: "#/components/schemas/Identifier"
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Server"
        "400":
          description: Invalid input
        "404":
          description: Server group not found
        "409":
          description: Server already exists
  "/api/v1/server/{name}":
    get:
      summary: Get the server
      operationId: getServer
      parameters:
        - name: name
          in: path
          description: Name of the server
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Server"
        "400":
          description: Invalid input
        "404":
          description: Server not found
    delete:
      summary: Delete an existing server
      operationId: removeServer
      parameters:
        - name: name
          in: path
          description: Name of the server
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid input
        "404":
          description: Server not found
  "/api/v1/server/{name}/start":
    post:
      summary: Start the server
      operationId: startServer
      parameters:
        - name: name
          in: path
          description: Name of the server
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid input
        "404":
          description: Server not found
  "/api/v1/server/{name}/stop":
    post:
      summary: Stop the server
      operationId: stopServer
      parameters:
        - name: name
          in: path
          description: Name of the server
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid input
        "404":
          description: Server not found
  "/api/v1/server/{name}/players":
    post:
      summary: Set the online players
      operationId: setOnlinePlayers
      requestBody:
        description: Set the online players
        content:
          application/json:
            schema:
              type: object
              properties:
                players:
                  type: integer
                  minimum: 0
                  example: 20

      parameters:
        - name: name
          in: path
          description: Name of the server
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - server
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid input
        "404":
          description: Server not found
  "/api/v1/template":
    get:
      summary: Get all templates
      operationId: getTemplates
      tags:
        - template
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Template"
    post:
      summary: Create a new template
      operationId: createTemplate
      parameters:
        - name: name
          in: query
          description: Name of the template
          example: lobby-template
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      requestBody:
        description: The tar binary of the template folder
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
        required: true
      tags:
        - template
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        "409":
          description: Template already exists
    put:
      summary: Update the files of the template
      operationId: updateTemplate
      parameters:
        - name: name
          in: query
          description: Name of the template
          example: lobby-template
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      requestBody:
        description: The tar binary of the template folder
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
        required: true
      tags:
        - template
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
  "/api/v1/template/{name}":
    get:
      summary: Get the template
      operationId: getTemplate
      parameters:
        - name: name
          in: path
          description: Name of the template
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - template
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        "400":
          description: Invalid input
        "404":
          description: Template not found
    delete:
      summary: Delete an existing template
      operationId: removeTemplate
      parameters:
        - name: name
          in: path
          description: Name of the template
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - template
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid input
        "403":
          description: Template in use
        "404":
          description: Template not found
  "/api/v1/template/{name}/download":
    get:
      summary: Downloads the template
      operationId: downloadTemplate
      parameters:
        - name: name
          in: path
          description: Name of the template
          required: true
          schema:
            $ref: "#/components/schemas/Identifier"
      tags:
        - template
      responses:
        "200":
          description: Successful operation
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "204":
          description: Empty template
        "400":
          description: Invalid input
        "404":
          description: Template not found
  "/api/v1/events":
    post:
      summary: "Monitor events"
      operationId: "listenEvents"
      tags: [ "system" ]
      requestBody:
        content:
          filters:
            schema:
              $ref: '#/components/schemas/EventsRequest'
      responses:
        "200":
          description: "No error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventMessage'
components:
  schemas:
    Template:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/Identifier"
        size:
          type: integer
          format: uint64
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Identifier:
      type: string
      pattern: ^[a-zA-Z0-9-_]{3,32}$
      minLength: 3
      maxLength: 32
    ServerGroup:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/Identifier"
        template:
          $ref: "#/components/schemas/Identifier"
        ports:
          type: array
          items:
            $ref: "#/components/schemas/Port"
        max-players-per-server:
          type: integer
          format: int32
          example: 20
    Port:
      type: object
      properties:
        name:
          type: string
          example: minecraft
        protocol:
          type: string
          enum:
            - tcp
            - udp
            - sctp
          example: tcp
        target-port:
          type: integer
          format: uint16
          example: 25565
        published-port:
          type: integer
          format: uint16
          example: 25565
        publish-mode:
          type: string
          example: ingress
          enum:
            - ingress
            - host
    Server:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/Identifier"
        group:
          $ref: "#/components/schemas/Identifier"
        ip-address:
          type: string
          example: 10.0.0.11
        status:
          type: string
          description: Server Status
          example: online
          enum:
            - starting
            - online
            - offline
        online-players:
          type: integer
          format: int32
          example: 4
          nullable: false
    ServerList:
      type: array
      items:
        $ref: "#/components/schemas/Server"
    EventsRequest:
      type: object
      properties:
        type:
          type: string
          enum: [ "server", "server-group", "template" ]
          example: "template"
        name:
          $ref: '#/components/schemas/Identifier'
    EventMessage:
      type: object
      properties:
        type:
          type: string
          example: server
          enum: [ "server", "server-group", "template" ]
        action:
          description: "The type of the event"
          type: string
          example: "create"
          enum: [ "create", "remove", "update" ]
        time:
          description: "Timestamp of the event"
          type: "integer"
          format: "uint64"
          example: 1629574695
        object:
          oneOf:
            - $ref: '#/components/schemas/Server'
            - $ref: '#/components/schemas/Template'
            - $ref: '#/components/schemas/ServerGroup'
#  securitySchemes:
#    petstore_auth:
#      type: oauth2
#      flows:
#        implicit:
#          authorizationUrl: https://petstore3.swagger.io/oauth/authorize
#          scopes:
#            write:pets: modify pets in your account
#            read:pets: read your pets
#    api_key:
#      type: apiKey
#      name: api_key
#      in: header