Basic API Yaml

api.yaml

swagger: '2.0'
info:
  title: Words API
  description: Get EasyRead word data!
  version: 1.0.0
host: game-test-api.herokuapp.com
schemes:
  - https
basePath: /api/v1
produces:
  - application/json
paths:
  /session:
    post:
      summary: Creates a game session
      description: |
        Creates a game session that can be used to track statistics for a given game.
      parameters:
        - name: userID
          in: query
          description: The unique identifier for the user that is initializing the game session.
          required: true
          type: string
          format: uuid
        - name: gameID
          in: query
          description: The unique identifier for the game that is initializing the session.
          required: true
          type: string
          format: uuid
      tags:
        - Games
      responses:
        '200':
          description: The session object
          schema:
            $ref: '#/definitions/Session'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /word:
    get:
      summary: A word object
      description: Returns a randomly selected object containing information about a word, including age information and any matches/non matches.
      parameters:
        - name: sessionID
          in: query
          description: The session to use to avoid word repitition.
          type: string
          format: uuid
        - name: age
          in: query
          description: The reading age of the required word.
          required: true
          type: number
          format: double
      tags:
        - Words
      responses:
        '200':
          description: The word object
          schema:
            $ref: '#/definitions/Word'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /feedback:
    post:
      summary: Creates a piece of feedback
      description: Feedback entries are relevant infomation about the progress of a given game. 
      parameters:
        - name: sessionID
          in: query
          description: The session session that this feedback should be marked against.
          type: string
          format: uuid
        - name: wordID
          in: query
          description: The word that this feedback should be marked against
          type: string
          format: uuid
        - name: userID
          in: query
          description: The user that this feedback should be marked against
          type: string
          format: uuid
        - name: respose
          in: query
          description: What the users response was
          type: boolean
        - name: correct
          in: query
          description: Whether the users response was correct or not
          type: boolean
        - name: responsetime
          in: query
          description: How long in milliseconds the user took to respond to the question
          type: number
          format: double
      tags:
        - Feedback
      responses:
        '200':
          description: The feedback object
          schema:
            $ref: '#/definitions/Feedback'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  Session:
    type: object
    properties:
      _id:
        type: string
        format: uuid
        description: The unique identifier for the created session.
      userID:
        type: string
        format: uuid
        description: The unique identifier for the user that created the session
      gameID:
        type: string
        format: uuid
        description: The unique identifier for the game that created the session
  Word:
    type: object
    properties:
      _id:
        type: string
        format: uuid
        description: The unique identifier for the given word.
      word:
        type: string
        description: The actual word.
      age:
        type: number
        format: double
        description: The approx reading age for the given word.
      matches:
        type: array
        description: a list of words that match the given word. Note that words in list will not contain any further matches/nonMatches.
        items:
          $ref: '#/definitions/Word'
      nonMatches:
        type: array
        description: a list of words that do not match the given word. Note that words in list will not contain any further matches/nonMatches.
        items:
          $ref: '#/definitions/Word'
      image:
        type: string
        description: URL to image for the given word
  Feedback:
    type: object
    properties:
      _id:
        type: string
        format: uuid
        description: The unique identifier for this piece of feedback.
      sessionID: 
        type: string
        format: uuid
        description: The sessionID for this piece of feedback
      wordID:
        description: The word that this feedback should be marked against
        type: string
        format: uuid
      userID:
        description: The user that this feedback should be marked against
        type: string
        format: uuid
      respose:
        description: What the users response was
        type: boolean
      correct:
        description: Whether the users response was correct or not
        type: boolean
      responsetime:
        description: How long in milliseconds the user took to respond to the question
        type: number
        format: double
      
  Error:
    type: object
    properties:
      message:
        type: string
        description: summary of the error received
      name:
        type: string
        description: type of error
      errors:
        type: object
        description: further detail of the individual errors for the request