Skip to content

Instantly share code, notes, and snippets.

@royletron
Last active November 26, 2015 20:13
Show Gist options
  • Save royletron/01ba5c4954953f93d591 to your computer and use it in GitHub Desktop.
Save royletron/01ba5c4954953f93d591 to your computer and use it in GitHub Desktop.
Basic 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment