gameontext.yaml

swagger: '2.0'
info:
  title: Game On
  description: |
    A throwback text application.  Check <a href='https://gameontext.org'>gameontext.org</a> for more info!
  version: 1.0.0
host: gameontext.org
schemes:
  - https
basePath: /
produces:
  - application/json
tags:
  - name: map
  - name: players
definitions:
  Site:
    type: object
    required:
      - _id
      - exits
      - info
      - owner
    properties:
      _id:
        type: string
        example: '1'
        description: Site id
        readOnly: true
      info:
        $ref: '#/definitions/RoomInfo'
      exits:
        $ref: '#/definitions/Exits'
      owner:
        type: string
        description: Owner
      created_on:
        type: string
        example: '2011-12-03T10:15:30Z'
        description: Date site created in ISO-8601 instant format
        readOnly: true
      assigned_on:
        type: string
        example: '2011-12-03T10:15:30Z'
        description: Date room assigned in ISO-8601 instant format
        readOnly: true
      coord:
        $ref: '#/definitions/Coordinates'
      createdInstant:
        type: integer
        format: int64
      assignedInstant:
        type: integer
        format: int64
    description: A room (or suite) is anchored into the map as a site when it is registered. The mapping should remain fairly stable unless a room is removed and re-appears.
  Exits:
    type: object
    properties:
      'n':
        $ref: '#/definitions/Exit'
      w:
        $ref: '#/definitions/Exit'
      s:
        $ref: '#/definitions/Exit'
      e:
        $ref: '#/definitions/Exit'
      u:
        $ref: '#/definitions/Exit'
      d:
        $ref: '#/definitions/Exit'
    description: 'When a room is placed in the map, paths are created between it and other rooms. Each exit provides the door and URL required for the player to traverse the path to the target room.'
  Doors:
    type: object
    properties:
      'n':
        type: string
        example: A knobbly wooden door with a rough carving or a friendly face
        description: North door (140 characters)
      w:
        type: string
        example: A fake wooden door with stickers of friendly faces plastered all over it
        description: West door (140 characters)
      s:
        type: string
        example: A warped wooden door with a friendly face branded on the corner
        description: South door (140 characters)
      e:
        type: string
        example: A polished wooden door with an inlaid friendly face
        description: East door (140 characters)
      u:
        type: string
        example: A scuffed and scratched oaken trap door
        description: Door in the ceiling (Up) (140 characters)
      d:
        type: string
        example: A rough-cut particle board hatch
        description: Door in the floor (Down) (140 characters)
    description: 'Descriptions for the doors in the room. These may be used by other rooms to describe the appearance of the door. Keys should be relative to this room (e, w, n, s, u, d). Values are simple string descriptions for the outside of the door. If the string value references a direction at all, it should be the opposite direction:for the East door, the direction mentioned should be West. Descriptions are optional, and will be generated if absent.'
  Coordinates:
    type: object
    required:
      - x
      - 'y'
    properties:
      x:
        type: integer
        format: int32
        description: X coordinate
      'y':
        type: integer
        format: int32
        description: Y coordinate
  ConnectionDetails:
    type: object
    required:
      - target
      - type
    properties:
      type:
        type: string
        example: websocket
        description: Connection type
      target:
        type: string
        example: 'ws://secondroom:9008/barn/ws'
        description: 'Connection target, usually a URL'
      token:
        type: string
        example: A-totally-arbitrary-really-long-string
        description: A token used for mutual identification between the room and the mediator during the initial handshake when the connection is established (optional)
      healthUrl:
        type: string
        example: 'http://secondroom:9008/barn/health'
        description: Health Check URL
    description: Connection details used by the mediator to connect to the room on the player's behalf
  RoomInfo:
    type: object
    required:
      - connectionDetails
      - name
    properties:
      name:
        type: string
        example: First Room
        description: 'Short/Terse name of the target room, must be unique within the owner''s rooms'
      connectionDetails:
        $ref: '#/definitions/ConnectionDetails'
      fullName:
        type: string
        example: The First Room
        description: Human-friendly room name
      description:
        type: string
        example: A helpful room with doors in every possible direction.
        description: Player-friendly room description (140 characters)
      repositoryUrl:
        type: string
        example: 'https://github.com/your-fork'
        description: Public Repository URL
      doors:
        $ref: '#/definitions/Doors'
    description: 'Mutable information: descriptive elements, service URL, etc.'
  Exit:
    type: object
    required:
      - _id
      - connectionDetails
      - door
      - name
    properties:
      _id:
        type: string
        example: '2'
        description: Id of the target room
        readOnly: true
      name:
        type: string
        example: Barn
        description: Short/Terse name of the target room
      fullName:
        type: string
        example: The First Room
        description: Human-friendly room name
      door:
        type: string
        example: Big red barn door
        description: Player-friendly description of the door (provided by the target room or generated by the map)
      connectionDetails:
        $ref: '#/definitions/ConnectionDetails'
    description: An exit provides the door and URL required for the player to traverse the path to the next room.
  PlayerResponse:
    type: object
    required:
      - _id
      - favoriteColor
      - location
      - name
    properties:
      _id:
        type: string
        example: 'oauthProvider:userid'
        description: Unique player id
        readOnly: true
      name:
        type: string
        example: Harriet
        description: Player name
      favoriteColor:
        type: string
        example: Tangerine
        description: Favorite color
      location:
        description: Player Location
        $ref: '#/definitions/PlayerLocation'
      credentials:
        description: Player Credentials
        $ref: '#/definitions/PlayerCredentials'
    description: Player account information
  LocationChange:
    type: object
    required:
      - newLocation
      - oldLocation
    properties:
      oldLocation:
        type: string
        example: room_id_1
        description: old player location
      newLocation:
        type: string
        example: room_id_1
        description: new player location
      origin:
        type: string
        example: origin_uuid
        description: uuid of request origin (not stored)
    description: Player location change
  PlayerArgument:
    type: object
    required:
      - _id
      - favoriteColor
      - name
    properties:
      _id:
        type: string
        example: 'oauthProvider:userid'
        description: Unique player id
        readOnly: true
      name:
        type: string
        example: Harriet
        description: Player name
      favoriteColor:
        type: string
        example: Tangerine
        description: Favorite color
    description: Player account information
  PlayerLocation:
    type: object
    required:
      - location
    properties:
      location:
        type: string
        example: room_id_1
        description: current player location
    description: Player location
  PlayerCredentials:
    type: object
    required:
      - sharedSecret
    properties:
      sharedSecret:
        type: string
        example: fjhre8h49hf438u9h45
        description: shared secret for player
    description: Player credentials
  ErrorResponse:
    type: object
    required:
      - message
      - status
    properties:
      status:
        type: integer
        format: int32
        example: 400
        description: Http Response code (for reference)
      message:
        type: string
        example: Unauthenticated client
        description: Error message
      more_info:
        type: string
        example: Room owner could not be determined.
        description: Optional additional information
    description: Error response
paths:
  /map/v1/sites:
    get:
      tags:
        - map
      summary: List sites
      description: Get a list of registered sites. Use link headers for pagination.
      operationId: listAll
      produces:
        - application/json
      parameters:
        - name: owner
          in: query
          description: filter by owner
          required: false
          type: string
        - name: name
          in: query
          description: filter by name
          required: false
          type: string
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              $ref: '#/definitions/Site'
        '204':
          description: No results found
    post:
      tags:
        - map
      summary: Create a room
      description: 'When a room is registered, the map will generate the appropriate paths to place the room into the map. The map wll only generate links using standard 2-d compass directions. The ''exits'' attribute in the return value describes connected/adjacent sites. '
      operationId: createRoom
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: New room attributes
          required: true
          schema:
            $ref: '#/definitions/RoomInfo'
      responses:
        '201':
          description: Successful
          schema:
            $ref: '#/definitions/Site'
        '400':
          description: Bad Request; details will explain what should be corrected before retrying
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Caller is not authorized to create room
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  '/map/v1/sites/{id}':
    get:
      tags:
        - map
      summary: Get a specific room
      description: ''
      operationId: getRoom
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: target room id
          required: true
          type: string
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/Site'
        '404':
          description: No results found
          schema:
            $ref: '#/definitions/ErrorResponse'
    put:
      tags:
        - map
      summary: Update a specific room
      description: ''
      operationId: updateRoom
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: target room id
          required: true
          type: string
        - in: body
          name: body
          description: Updated room attributes
          required: true
          schema:
            $ref: '#/definitions/RoomInfo'
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/Site'
        '400':
          description: Bad Request; details will explain what should be corrected before retrying
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Caller is not authorized to update room
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: No results found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete:
      tags:
        - map
      summary: Delete a specific room
      description: ''
      operationId: deleteRoom
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: target room id
          required: true
          type: string
      responses:
        '204':
          description: Successful
        '400':
          description: Bad Request; details will explain what should be corrected before retrying
          schema:
            $ref: '#/definitions/ErrorResponse'
        '403':
          description: Caller is not authorized to delete room
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: No results found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  /players/v1/accounts:
    get:
      tags:
        - players
      summary: List all players
      description: Get a list of registered players. Use link headers for pagination.
      operationId: getAllPlayers
      produces:
        - application/json
      parameters: []
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerResponse'
        '204':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    post:
      tags:
        - players
      summary: Create a new player account
      description: ''
      operationId: createPlayer
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: false
          schema:
            $ref: '#/definitions/PlayerArgument'
      responses:
        '201':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerResponse'
        '403':
          description: Authenticated user id must match new player id
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  '/players/v1/accounts/{id}':
    get:
      tags:
        - players
      summary: Get a specific player
      description: ''
      operationId: getPlayerInformation
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: target player id
          required: true
          type: string
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerResponse'
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
    put:
      tags:
        - players
      summary: Update a specific player
      description: ''
      operationId: updatePlayer
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: target player id
          required: true
          type: string
        - in: body
          name: body
          description: Updated player attributes
          required: true
          schema:
            $ref: '#/definitions/PlayerArgument'
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerResponse'
        '403':
          description: Caller is not authorized to update specified player
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete:
      tags:
        - players
      summary: Delete a specific player
      description: ''
      operationId: removePlayer
      parameters:
        - name: id
          in: path
          description: target player id
          required: true
          type: string
      responses:
        '204':
          description: Successful
        '403':
          description: Caller is not authorized to delete specified player
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  '/players/v1/accounts/{id}/credentials':
    get:
      tags:
        - players
      summary: Get credentials for a specific player
      description: ''
      operationId: getPlayerCredentials
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: target player id
          required: true
          type: string
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerCredentials'
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  '/players/v1/accounts/{id}/credentials/sharedSecret':
    put:
      tags:
        - players
      summary: Update player shared secret
      description: ''
      operationId: updatePlayerApiKey
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerArgument'
        '403':
          description: Caller is not authorized to  update player shared secret
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  '/players/v1/accounts/{id}/location':
    get:
      tags:
        - players
      summary: Get a specific player location
      description: 'returns a map of player id to location, location can be null if historically the player has never had a location stored.'
      operationId: getPlayerLocation
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: target player id
          required: true
          type: string
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerLocation'
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
    put:
      tags:
        - players
      summary: Update player location
      description: ''
      operationId: updatePlayerLocation
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
        - in: body
          name: body
          required: false
          schema:
            $ref: '#/definitions/LocationChange'
      responses:
        '200':
          description: Successful
          schema:
            $ref: '#/definitions/PlayerLocation'
        '403':
          description: Caller is not authorized to update player location
          schema:
            $ref: '#/definitions/ErrorResponse'
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '409':
          description: Save conflict
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  /players/v1/color:
    get:
      tags:
        - players
      summary: Get ten generated colors
      description: ''
      operationId: getColors
      produces:
        - application/json
      parameters: []
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              type: string
    parameters: []
  /players/v1/locations:
    get:
      tags:
        - players
      summary: Get player locations.
      description: 'can pass optional params playerId to retrieve only location for player, or siteId to retrieve players in a location, combining the two will return an empty map if the player is not in that location'
      operationId: getPlayerLocationInformation
      produces:
        - application/json
      parameters:
        - name: playerId
          in: query
          description: target player id
          required: false
          type: string
        - name: siteId
          in: query
          description: target site id
          required: false
          type: string
      responses:
        '200':
          description: Successful
        '404':
          description: Player not found
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters: []
  /players/v1/name:
    get:
      tags:
        - players
      summary: Get ten randomly generated player names
      description: ''
      operationId: getNames
      produces:
        - application/json
      parameters: []
      responses:
        '200':
          description: Successful
          schema:
            type: array
            items:
              type: string
    parameters: []