rove/swagger.yml

swagger: "2.0"
info:
  description: "Rove is an asychronous nomadic game about exploring a planet as part of a loose community"
  version: "0.1"
  title: "Rove Server"
host: "api.rove-game.com:8080"
basePath: "/"
tags:
- name: "server"
  description: "Interactions with the server itself"
- name: "accounts"
  description: "Access to accounts"
- name: "rove"
  description: "Operations for the game"
schemes:
- "http"
consumes:
  - application/json
produces:
  - application/json
paths:
  /status:
    get:
      tags:
      - "server"
      summary: "Server status"
      description: "Responds with various details about the current server status"
      operationId: "Status"
      responses:
        "200":
          description: "Server is active"
          schema:
            $ref: '#/definitions/status'
  /register:
    post:
      tags:
        - "accounts"
      summary: "Register an account"
      description: "Tries to register an account with the given name"
      operationId: "Register"
      parameters:
        - in: body
          name: name
          schema:
            $ref: '#/definitions/register-data'
      responses:
        "200":
          description: "Successfully created account"
        "400":
          description: "Bad request, typically due to duplicate name"
          schema:
            $ref: '#/definitions/error'
        "500":
          description: "Server encountered error, please report this as a bug"
          schema:
            $ref: '#/definitions/error'

  /{account}/commands:
    post:
      tags:
        - rove
      summary: Send commands to rover
      description: "Sending commands to this endpoint will queue them to be executed during the following ticks, in the order sent"
      operationId: "Commands"
      parameters:
        - in: path
          name: account
          required: true
          type: string
        - in: body
          name: commands
          schema:
            $ref: '#/definitions/commands-data'
      responses:
        "200":
          description: "Successfully queued commands"
        "400":
          description: "Bad request, typically due to unknown command parameters"
          schema:
            $ref: '#/definitions/error'
        "500":
          description: "Server encountered error, please report this as a bug"
          schema:
            $ref: '#/definitions/error'

  /{account}/radar:
    get:
      tags:
        - rove
      summary: Get radar information
      description: "Gets the radar output for the given rover"
      operationId: "Radar"
      parameters:
        - in: path
          name: account
          required: true
          type: string
      responses:
        "200":
          description: "Successfully returned rover radar"
          schema:
            $ref: '#/definitions/radar-response'
        "400":
          description: "Bad request, typically due to unknown account"
          schema:
            $ref: '#/definitions/error'
        "500":
          description: "Server encountered error, please report this as a bug"
          schema:
            $ref: '#/definitions/error'

  /{account}/rover:
    get:
      tags:
        - rove
      summary: Get rover information
      description: "Gets information for the account's rover"
      operationId: "Rover"
      parameters:
        - in: path
          name: account
          required: true
          type: string
      responses:
        "200":
          description: "Successfully returned rover information"
          schema:
            $ref: '#/definitions/rover-response'
        "400":
          description: "Bad request, typically due to unknown account"
          schema:
            $ref: '#/definitions/error'
        "500":
          description: "Server encountered error, please report this as a bug"
          schema:
            $ref: '#/definitions/error'

definitions:
  status:
    properties:
      ready:
        description: Whether the server is ready to accept requests
        type: boolean
        example: true
      version:
        description: The version of the server in v{major}.{minor}-{delta}-{sha} form
        type: string
        example: "v0.12-1-g7d1a2d7"
      tick:
        description: The tick rate of the server in minutes (how many minutes per tick)
        type: integer
        example: 5
      nexttick:
        description: The time the next tick will occur
        type: string
        example: "15:30:00"

  error:
    properties:
      error:
        description: An explanation for the HTTP error returned
        type: string
        example: "account not found"

  register-data:
    properties:
      name:
        description: The account name
        type: string
        example: "myname"
    required:
      - name

  command:
    properties:
      command:
        description: "The command to execute, currently only accepts move, which requires a bearing and a duration."
        type: string
        example: move
      bearing:
        type: string
        example: NE
      duration:
        type: integer
        example: 5

  commands-data:
    properties:
      commands:
        description: A set of commands to exectute in the order given
        type: array
        items:
          type: object
          properties:
            schema:
              $ref: '#/definitions/command'

  radar-response:
    properties:
      range:
        description: The range in tiles from the rover of the radar data
        type: integer
        example: 5
      tiles:
        description: A 1D array representing range*2 + 1 squared set of tiles, origin bottom left and in row->column order
        type: array
        items:
          type: integer

  vector:
    properties:
      'x':
        type: integer
        example: 1
      'y':
        type: integer
        example: 2

  rover-attributes:
    properties:
      speed:
        description: The speed the rover can move per tick
        type: integer
        example: 1
      range:
        description: The range of this rover's radar
        type: integer
        example: 5
      name:
        description: The name of the rover
        type: string
        example: rover-one
      position:
        description: Position of the rover in world coordinates
        type: object
        properties:
          schema:
            $ref: '#/definitions/vector'

  rover-response:
    properties:
      attributes:
          description: The attributes of the given rover
          type: object
          $ref: '#/definitions/rover-attributes'