CQTSOG Open API Spec - CreoDAMO/CQTSOG-MMORPG GitHub Wiki

OpenAPI specification for CryptoQuest: The Shards of Genesis project:

openapi: 3.0.3
info:
  title: CryptoQuest: The Shards of Genesis API
  description: API for managing CryptoQuest game features, including NFT assets, player interactions, and marketplace transactions.
  version: 1.0.0
servers:
  - url: https://api.cryptoquest.com/v1
    description: Main production server
  - url: https://api.staging.cryptoquest.com/v1
    description: Staging server for testing

paths:
  /nfts:
    get:
      summary: Get a list of NFTs
      tags: [NFTs]
      responses:
        '200':
          description: A list of NFTs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NFT'
    post:
      summary: Create a new NFT
      tags: [NFTs]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewNFT'
      responses:
        '201':
          description: NFT created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFT'
  /nfts/{id}:
    get:
      summary: Get an NFT by ID
      tags: [NFTs]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single NFT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFT'
        '404':
          description: NFT not found
    put:
      summary: Update an NFT
      tags: [NFTs]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNFT'
      responses:
        '200':
          description: NFT updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NFT'
        '404':
          description: NFT not found
    delete:
      summary: Delete an NFT
      tags: [NFTs]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: NFT deleted successfully
        '404':
          description: NFT not found

  /players:
    get:
      summary: Get a list of players
      tags: [Players]
      responses:
        '200':
          description: A list of players
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Player'
    post:
      summary: Create a new player
      tags: [Players]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPlayer'
      responses:
        '201':
          description: Player created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
  /players/{id}:
    get:
      summary: Get a player by ID
      tags: [Players]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single player
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
        '404':
          description: Player not found
    put:
      summary: Update a player
      tags: [Players]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePlayer'
      responses:
        '200':
          description: Player updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
        '404':
          description: Player not found
    delete:
      summary: Delete a player
      tags: [Players]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Player deleted successfully
        '404':
          description: Player not found

  /marketplace:
    get:
      summary: Get a list of marketplace transactions
      tags: [Marketplace]
      responses:
        '200':
          description: A list of marketplace transactions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketplaceTransaction'
    post:
      summary: Create a new marketplace transaction
      tags: [Marketplace]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMarketplaceTransaction'
      responses:
        '201':
          description: Marketplace transaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceTransaction'
  /marketplace/{id}:
    get:
      summary: Get a marketplace transaction by ID
      tags: [Marketplace]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single marketplace transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceTransaction'
        '404':
          description: Marketplace transaction not found
    put:
      summary: Update a marketplace transaction
      tags: [Marketplace]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMarketplaceTransaction'
      responses:
        '200':
          description: Marketplace transaction updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceTransaction'
        '404':
          description: Marketplace transaction not found
    delete:
      summary: Delete a marketplace transaction
      tags: [Marketplace]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Marketplace transaction deleted successfully
        '404':
          description: Marketplace transaction not found

components:
  schemas:
    NFT:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        image:
          type: string
        attributes:
          type: array
          items:
            type: object
            properties:
              trait_type:
                type: string
              value:
                type: string
    NewNFT:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        image:
          type: string
        attributes:
          type: array
          items:
            type: object
            properties:
              trait_type:
                type: string
              value:
                type: string
      required:
        - name
        - description
        - image
    UpdateNFT:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        image:
          type: string
        attributes:
          type: array
          items:
            type: object
            properties:
              trait_type:
                type: string
              value:
                type: string

    Player:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        level:
          type: integer
        experience:
          type: integer
        walletAddress:
          type: string
    NewPlayer:
      type: object
      properties:
        username:
          type: string
        walletAddress:
          type: string
      required:
        - username
        - walletAddress
    UpdatePlayer:
      type: object
      properties:
        username:
          type: string
        level:
          type: integer
        experience:
          type: integer
        walletAddress:
          type: string

    MarketplaceTransaction:
      type: object
      properties:
        id:
          type: string
        nftId:
          type: string
        sellerId:
          type: string
        buyerId:
          type: string
        price:
          type: number
    NewMarketplaceTransaction:
      type: object
      properties:
        nftId:
          type: string
        sellerId:
          type: string
        buyerId:
          type: string
        price:
          type: number
      required:
        - nftId
        - sellerId
        - buyerId
        - price
    UpdateMarketplaceTransaction:
      type: object
      properties:
        nftId:
          type: string
        sellerId:
          type: string
        buyerId:
          type: string
        price:
          type: number

Explanation:

1. Info Section: Provides basic information about the API, including

title, description, and version. 2. Servers Section: Lists the API servers, including production and staging environments. 3. Paths Section: Defines the API endpoints (/nfts, /nfts/{id}, /players, /players/{id}, /marketplace, /marketplace/{id}) and the operations available on each endpoint (GET, POST, PUT, DELETE). 4. Components Section: Contains reusable schemas for NFT, Player, and MarketplaceTransaction objects, as well as the request bodies for creating and updating these objects.

This OpenAPI specification provides a comprehensive structure for the CryptoQuest API, ensuring that it is well-documented and easily understandable for developers.