openapi: 3.0.0
info:
  version: 2.0.0
  title: TWHelp API
  description: REST API to interact with [TWHelp](https://tribalwarshelp.com).
  contact:
    name: Dawid Wysokiński
    url: https://dwysokinski.me
    email: contact@dwysokinski.me
  license:
    name: MIT
tags:
  - name: versions
  - name: servers
servers:
  - url: "{scheme}://{hostname}/api"
    variables:
      scheme:
        default: http
        enum:
          - http
          - https
      hostname:
        default: localhost:9234
paths:
  /v2/versions:
    get:
      operationId: listVersions
      tags:
        - versions
      description: List versions
      parameters:
        - $ref: "#/components/parameters/CursorQueryParam"
        - $ref: "#/components/parameters/LimitQueryParam"
      responses:
        200:
          $ref: "#/components/responses/ListVersionsResponse"
        default:
          $ref: "#/components/responses/ErrorResponse"
  /v2/versions/{versionCode}:
    get:
      operationId: getVersion
      tags:
        - versions
      description: Get a version
      parameters:
        - $ref: "#/components/parameters/VersionCodePathParam"
      responses:
        200:
          $ref: "#/components/responses/GetVersionResponse"
        default:
          $ref: "#/components/responses/ErrorResponse"
  /v2/versions/{versionCode}/servers:
    get:
      operationId: listServers
      tags:
        - versions
        - servers
      description: List servers
      parameters:
        - $ref: "#/components/parameters/VersionCodePathParam"
        - $ref: "#/components/parameters/CursorQueryParam"
        - $ref: "#/components/parameters/LimitQueryParam"
        - $ref: "#/components/parameters/ServerOpenQueryParam"
      responses:
        200:
          $ref: "#/components/responses/ListServersResponse"
        default:
          $ref: "#/components/responses/ErrorResponse"
components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      additionalProperties: false
      properties:
        code:
          type: string
          example: length-out-of-range
        message:
          type: string
        path:
          type: array
          description: References field where an error occurred.
          items:
            type: string
          x-go-type-skip-optional-pointer: true
        params:
          type: object
          description: Additional data related to the error. Can be used for i18n.
          additionalProperties: true
          x-go-type-skip-optional-pointer: true
    Version:
      type: object
      required:
        - code
        - host
        - name
        - timezone
      properties:
        code:
          type: string
          example: pl
        host:
          type: string
          example: www.tribalwars.net
        name:
          type: string
          example: Poland
        timezone:
          type: string
          example: Europe/Warsaw
    Server:
      type: object
      required:
        - key
        - open
        - url
        - numPlayers
        - numTribes
        - numVillages
        - numBarbarianVillages
        - numBonusVillages
        - numPlayerVillages
        - createdAt
      properties:
        key:
          type: string
          example: pl151
        open:
          type: boolean
        url:
          type: string
          example: https://pl151.plemiona.pl
        numPlayers:
          type: integer
        playerDataSyncedAt:
          type: string
          format: date-time
        numTribes:
          type: integer
        tribeDataSyncedAt:
          type: string
          format: date-time
        numVillages:
          type: integer
        numBarbarianVillages:
          type: integer
        numBonusVillages:
          type: integer
        numPlayerVillages:
          type: integer
        villageDataSyncedAt:
          type: string
          format: date-time
        ennoblementDataSyncedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    Cursor:
      type: object
      x-go-type-skip-optional-pointer: true
      properties:
        self:
          description: Cursor pointing to the current page.
          type: string
          x-go-type-skip-optional-pointer: true
        next:
          description: Cursor pointing to the next page.
          type: string
          x-go-type-skip-optional-pointer: true
    PaginationResponse:
      type: object
      properties:
        cursor:
          $ref: "#/components/schemas/Cursor"
  parameters:
    CursorQueryParam:
      in: query
      name: cursor
      schema:
        type: string
      required: false
    LimitQueryParam:
      in: query
      name: limit
      schema:
        type: integer
      required: false
    ServerOpenQueryParam:
      name: open
      in: query
      description: true=only open servers, false=only closed servers,
        by default both open and closed servers are returned
      schema:
        type: boolean
      required: false
    VersionCodePathParam:
      in: path
      name: versionCode
      required: true
      schema:
        type: string
  responses:
    ListVersionsResponse:
      description: ""
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/PaginationResponse"
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Version"
    GetVersionResponse:
      description: ""
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              data:
                $ref: "#/components/schemas/Version"
    ListServersResponse:
      description: ""
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/PaginationResponse"
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Server"
    ErrorResponse:
      description: Default error response.
      content:
        application/json:
          schema:
            type: object
            required:
              - errors
            additionalProperties: false
            properties:
              errors:
                type: array
                items:
                  $ref: "#/components/schemas/Error"