apiary.apib

FORMAT: 1A
HOST: https://nemestats.com/api/v2

# NemeStats API

[NemeStats.com](http://nemestats.com/) is a completely free and open source website for tracking the results of played games. 
We've made the API completely accessible so you can can use the NemeStats platform as your 
repository for all of your played game statistics. Most of the data pushed into the platform is
publicly accessible, but you can use the platform with no strings attached. 

The API could be useful for building your own mobile app, pulling out data for analysis, or
integrating with your own website or other application.

Feel free to email us at nemestats@gmail.com if you have questions or issues.

###Version Information
This document represents Version 2 of the API, which has the following changes from the previous version:
* /GamingGroups/{gamingGroupId}/ is removed from many of the service URIs in favor of the query string parameter for
GET requests and a body parameter for POST requests. Creating a Player, Game Definition, or Played Game now allows you to
optionally specify the gamingGroupId of the Gaming Group where the entity should be created. This is handy for
situations when a User is in multiple Gaming Groups.
For Example, /api/v1/GamingGroups/{gamingGroupid}/GameDefinitions is now /api/v2/GameDefinitions/?gamingGroupId=1
* Authorization is no longer required on a number of resources that were previously locked down. This is an attempt to
make more of the information freely available to API consumers. Information like usernames, passwords, and email will always remain private
and protected.
* Documentation for version 1 of the API can be found here: http://docs.nemestats.apiary.io/#

###Change Log

* 2015-10-09 Added playerActive boolean value to PlayerGameResults, so you can conveniently tell whether the Player is still active.
* 2016-01-26 Added the ability to filter Played Games on datePlayedFrom and datePlayedTo.
* 2016-03-17 Added ability to specify gamingGroupId in POST body when creating Players, Game Definitions, and Played Games 
for users with multiple Gaming Groups. Also returns gamingGroupId whenever creating a new entity since specifying gamingGroupId is not required, and this will
enable the client to know on exactly which Gaming Group the entity was created.
* 2016-03-25 Added bonus points for Game Weight and Average Game Duration: https://nemestats.com/Home/AboutNemePoints .
This means the existing nemeStatsPointsAwarded field on the playerGameResult object is now the base points that are awarded. This  value doesn't
change in the new  model, but if you want to get total points including the Game Weight and Game Duration Bonus Points,
then you need to use the playerGameResult.totalNemeStatsPointsAwarded.
* 2016-04-09 PointsScored on PlayerGameResult is now a decimal instead of an int.
* 2016-05-12 Updated all documentation to use nemestats.com domain instead of nerdscorekeeper.azurewebsites.net since we now support this. The old
domain should continue to work in the meantime, however.
* 2016-06-03 Added authenticationTokenExpirationDateTime to the results of the registration (POST /Users/) and sign in (POST /UserSessions/) services.
* 2016-07-22 Fixed API issue where newly created Players and Game Definitions were always placed in the User's default Gaming Group and not the one specified.
Also added a 409 conflict response to POST /PlayedGames/ if any of the Players don't exist in the specified Gaming Group. Also re-fixed an issue where it wasn't
accepting decimal places in pointsScored
* 2016-08-31 Can now set a list of applicationLinkages when recording a Played Game. This will allow clients to save their own unique identifier for games and retrieve games based on this identifier. For example, a client could import all games that do not have a source application matching their application.
* 2016-09-13 Can now pass flag "preserveExistingAuthenticationToken" to POST /UserSessions and it will not overwrite the existing authentication token.
* 2016-10-28 Fixed major design issue with previous change and eliminated "preserveExistingAuthenticationToken" entirely in favor of a new optional field "uniqueDeviceId" so you can create a separate auth token per device.
* 2016-11-07 Added support for PUT /PlayedGames/ for editing existing Played Games.
* 2017-09-19 Removed linkedPlayerId from documentation of the GET /Users endpoint since it was never implemented.

### General Information

* The API is versioned in the URL and will update whenever there are breaking changes to the API. 
That is, if a single service has a breaking change then all of the services will still continue 
to function on the old version, but all services (especially the updated ones) will be advanced to
the new version. 
Here is an example of a versioned endpoint: 

  `/api/v2/GamingGroup/1234`
* The general format for a URI is: 

  `/api/v{API version number}/{resource name}/{optional resource id}/{optional nested resource}/{optional nested resource id}`/{query string parameters}  

  An example would be GET /api/v2/PlayedGames/&gamingGroupId=1 (returns all of the Played Game resources with
  Gaming Group Id '1')
* Resource names are plural (e.g. GamingGroups instead of GamingGroup)
* Properties in request and response objects are camel-cased (e.g. playerId instead of PlayerId or playerid)
* For GET requests, additional parameters or filters will be passed in via query string (e.g.`/api/v2/Playedgames/?gamingGroupId=123&startDate=2015-02-03`)
* For services that require authentication (namely ones that allow data to be changed via POST/PUT/DELETE), a header for "X-Auth-Token" will need to be sent on the request to ensure that the consumer has the appropriate access.
* All dates will be in the ISO-8601 format ([wikipedia entry](http://en.wikipedia.org/wiki/ISO_8601)). In most cases this will just be the date portion in UTC (yyyy-MM-dd) with no time information included. For example: 2015-03-20
* Currently all services return data in JSON format only
* All services work only over HTTPS
* HTTP Status Codes
  * HTTP 200 or 204 will be returned on a normal success
  * For services that require authorization (i.e. those that require an X-Auth-Token header), 
  the service will return an HTTP 400 Bad Request response if the token is missing and an HTTP 401 Not Authorized response if the token is there, but is no longer valid.
  * HTTP 500 will be returned whenever there is an error on the server
  * Any other HTTP response codes will be explicitly documented in the respective service

# Data Structures

## PlayerRank (object)
Represents the minimum amount of data the the client needs to send to give rank information about a particular Player in a particular Played Game.
+ playerId (number, required) - NemeStats unique identifier for the Player.
+ gameRank (number, required) - The corresponding rank of the Player in this Played Game. A rank of 1 means the Player got first place, 2 means second place, and so on.
+ pointsScored (number, optional) - Decimal number of points the Player scored in the Played Game. Valid examples are -1, 20, 15.75, etc.

## PlayerGameResult (object)
Represents all of the data related to a particular Player's performance in a particular Played Game.
+ playerId (number, required) - NemeStats unique identifier for the Player.
+ playerName (string, required) - The name of the Player.
+ playerActive (bool, required) - Boolean value indicating whether the player is currently Active.
+ gameRank (number, required) - The corresponding integer rank of the Player in this Played Game. A rank of 1 means the Player got first place, 2 means second place, and so on.
+ pointsScored (number, optional) - Decimal number of points the Player scored in the Played Game.
+ nemeStatsPointsAwarded (number, required) - The number of NemeStats Points awarded to the Player for their respective rank in the Played Game.
+ gameDurationBonusNemePoints  (number, required) - The number of bonus NemeStats Points awarded due to the BoardGameGeek average Play Time of this Game Definition.
+ gameWeightBonusNemePoints (number, required) - The number of bonus NemeStats Points awarded due to the BoardGameGeek Weight of this Game Definition.
+ totalNemeStatsPointsAwarded (number, required) - The total number of NemeStats Points awarded including all bonus points.

## ApplicationLinkage (object)
Represents a unique identifier for an external application that also stores a representation of this Played Game. For example, if a Played Game is also in BoardGameGeek, the client could set an applicationLinkage with the applicationName = "BGG" and the entityId = "1399193".
+ applicationName (string, required) - Unique identifier for an external application which also holds a representation of this play. Use "BGG" for BoardGameGeek and "BGStats" for Board Game Stats. Other applications can use different application names, so long as they are unique.
+ entityId (string, required) - Unique identifier within the external application. For example, BoardGameGeek has an "id" value for each play which could be passed in this field.

# Group Authentication

Some services within NemeStats are completely wide open and do not require any security to prevent
unauthorized access. However, many services (such as those that post data to a Gaming Group) require
a valid NemeStats User account which is then in turn used to get an authorization token (i.e. an X-Auth-Token)
to send on the request header. The following services are related to creating User accounts (and hence 
Gaming Groups) as well as creating a User Session which provides an authentication token to send on
subsequent requests to the service.

# User [/Users/]
 A User represents an individual account with its own credentials to log into NemeStats.
 A User can have more than Gaming Group and hence more than one Player associated with it. It is
 necessary to create a User before you can request an authentication token to send on subsequent
 requests to the API.

## Register a new User [POST]
Register a new User and Gaming Group at the same time. Once a User account is created then requests can be made
to the User Sessions resource to give back and authentication token. Registering a new User will
also create a single Player with the same name as the new User. A confirmation email will be 
sent to the email address of the new User. 

+ Attributes
    + emailAddress : someemail@mailinator.com (string, required) - Email address of the User
    + userName : some username (string, required) - NemeStats username
    + password : some new password (string, required) - NemeStats password
    + uniqueDeviceId : some unique key for the user's device (string, optional) - A unique identifier for the device of the user. It only needs to be unique in 
    relation to the other devices that a User may have. For example, this could be used if a User has an iPhone and iPad
    and needs to get a different auth token for both. If there can only ever be one client device for the User then this can be omitted. 

+ Request Valid UserName (application/json)

+ Response 200 (application/json)
    
    + Attributes
        + userId : some user id (string, required) - NemeStats unique identifier of the newly registered user. May be
        used in the future to pull statistics for a given User (but currently has no use in the API).
        + playerId : 7980 (number, required) - NemeStats unique identifier for the corresponding Player 
        that was created and associated with the newly created User.
        + playerName : some username (string, required) - The name of the Player that was just created. Defaults to
        the same name of the newly created User.
        + gamingGroupId : 6326 (number, required) - The NemeStats unique identifier of the Gaming Group that was created as part
        of the User registration. The new User and Player are automatically placed in this Gaming Group.
        This id wiall be important for subsequent requests to the API and should definitely be stored
        client-side.
        + gamingGroupName : some username's Gaming Group (string, required) - The name of the newly created Gaming Group.
        + authenticationToken : `6ce40b88-d366-4c5d-b60d-cfbd9107bcd9` (string, required) - The token that should be sent in the X\-Auth\-Token request header on
        subsequent requests to the API that require authentication.
        + authenticationTokenExpirationDateTime : `2016-09-03T16:47:10.387` (string, required) - The date and time (ISO-8601 format) in which the authentication token will expire.
        Upon expiration, subsequent requests to the API using this token will return a 401 Not Authorized. 
    

+ Request Already In Use UserName (application/json)

                {
                  "emailAddress" : "someemail@mailinator.com",
                  "userName" : "some username that is already taken",
                  "password" : "some new password"
                }
                
+ Response 400 (application/json)

                {
                    "message" : "Name 'some username' is already taken."
                }

+ Request Already In Use Email (application/json)

                {
                  "emailAddress" : "someemailthatisalreadytaken@mailinator.com",
                  "userName" : "some username",
                  "password" : "some new password"
                }
                
+ Response 400 (application/json)

                {
                    "message" : "Email 'someemailthatisalreadytaken@mailinator.com' is already taken."
                }

## Get User Information [GET /Users/{userId}] 
Retrieve basic information for a given User. This service is secured so that only an X-Auth-Token for the requested User
will return a valid response.

+ Parameters
    + userId : some guid user id (string, required) - The NemeStats unique identifier for the User.
    
+ Request ValidRequest (application/json)
    + Headers
            
            X-Auth-Token: the token for the requested user
            
+ Response 200 (application/json)

                {
                    "userName" : "sparklepants",
                    "emailAddress" : "sparklepants@mailinator.com",
                    "gamingGroups" : [ 
                        {
                            "gamingGroupId" : "209",
                            "gamingGroupName" : "sparklepants's Gaming Group",
                            "gamingGroupPublicDescription" : "This group was created to record games we play as a family on the weekends."
                        },
                        {
                            "gamingGroupId" : "225",
                            "gamingGroupName" : "Weekend Warriors",
                            "gamingGroupPublicDescription" : "We are the Weekend Warriors and we like to play Magic the Gathering, Dominion, Star Realms, and other deck-building games. We play on the weekends at Dominic's Gaming House in downtown Mumbai. Email us at dgh@mailinator.com for details.",
                            "gamingGroupPublicUrl" : "https://dghmumbai.com"
                        }
                        ],
                    "players" : [
                    {
                      "playerId": 1569,
                      "playerName": "sparklepants",
                      "gamingGroupId": 209
                    },
                    {
                      "playerId": 1995,
                      "playerName": "sparklepants",
                      "gamingGroupId": 225
                    }
                }

+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }

# User Session [/UserSessions/]
 A User Session represents a period of time when a User is authenticated with NemeStats. A User Session
 must be created and the resulting authentication token must be passed on subsequent requests to the API
 in the X-Auth-Token header (for services that require authentication).

## Create a new User Session [POST]
Authenticates the given User and gives back an authentication token which can be sent in the X-Auth-Token
header on subsequent requests to the API that require authentication. This authentication token will be valid
for about 3 months or until another request to POST /UserSessions/ invalidates the token (while providing a new one).
You can pass the uniqueDeviceId to get a different authenticationToken per device.

A User Session is represented by an authentication token.

+ Request ValidCredentials (application/json)
                
    + Attributes
        + userName : some legit username (string, required) - Username of the User being authenticated
        + password : some legit password (string, required) - Password of the User being authenticated
        + uniqueDeviceId : desome unique key for the user's device (string, optional) - A unique identifier for the device of the user. It only needs to be unique in 
        relation to the other devices that a User may have. For example, this could be used if a User has an iPhone and iPad
        and needs to get a different auth token for both. Getting a new UserSession using the same uniqueDeviceId will override/invalidate the 
        previous auth token for that device.

+ Response 200 (application/json)

    + Attributes    
        + authenticationToken : some awesome token (string, required) - NemeStats unique identifier for the new User
        + authenticationTokenExpirationDateTime : `2016-09-03T16:47:10.387` (string, required) - The date and time (ISO-8601 format) in which the authentication token will expire.
        Upon expiration, subsequent requests to the API using this token will return a 401 Not Authorized.

+ Request InvalidCredentials (application/json)
                
                {
                  "userName" : "some invalid username",
                  "password" : "some invalid password"
                }
                
+ Response 401 (application/json)

                {
                    "message" : "Invalid credentials provided."
                }

# Group Gaming Groups
A Gaming Group represents a group of Players who play games together. The original User that registers
will have a new Gaming Group automatically created and associated with their account. Other Users
can be invited (currently through the website only) to join a Gaming Group and can even create 
additional Gaming Groups of their own. All Players, Game Definitions, and Played Games are associated
with exactly one Gaming Group. These resources are described in more detail in their 
corresponding sections.

# Played Games [/PlayedGames/]
A Played Game represents an event in which multiple Players were recorded as having played a 
given game (aka Game Definition in NemeStats terms). A Played Game houses information about
who played the game, who won, how many points were awarded, etc. The Played Game is the foundation
for all important statistics within NemeStats.

Currently, updating Played Games is not supported and requires that the game needing updates be deleted
and then recreated using the corresponding services for this.

+ Attributes
    + playedGameId (number, required) - NemeStats unique identifier for the Played Game.
    + gameDefinitionId (number, required) - NemeStats unique identifier for the Game Definition of the Played Game.
    + gameDefinitionName (string, required) - Name of the Game Definition.
    + boardGameGeekObjectId (number, optional) - Board Game Geek unique identifier for the Game Definition.
    + gamingGroupId (number, required) - NemeStats unique identifier of the Gaming Group against which this Played Game was recorded.
    + gamingGroupName (string, required) - Name of the Gaming Group.
    + notes (string, optional) - User-entered notes about the game.

    + datePlayed (string, required) - The date that the Played Game was recorded in yyyy-MM-dd format (e.g. 2015-05-013).
    + dateLastUpdated (string, required) - The date that the Played Game was last updated in yyyy-MM-dd format (e.g. 2015-05-013). This will usually match the datePlayed unless the Played Game was updated at a later date.
    + playerGameResults (PlayerGameResult, required) - A list of PlayerGameResult objects which contain information regarding each Player's rank, points scored, and NemeStats points awarded for playing the game.
    + applicationLinkages (ApplicationLinkage, optional) - A list of optional ApplicationLinkage objects which specify applicationName/entityId pairs representing the unique identifer for the Played Game in an external system. This combination must be unique within in a Gaming Group.

## Create a new Played Game [POST]
This service will record a new Played Game under the specified Gaming Group (per the gamingGroupId). 

+ Attributes
    + gameDefinitionId (number, required) - NemeStats unique identifier for the Game Definition (e.g. Race For the Galaxy's unique Id) of the Played Game.
    + gamingGroupId (number, optional) - The NemeStats unique identifier for the Gaming Group where the Played Game will be logged. If no gamingGroupId is specified, the Played Game will be recorded under the default Gaming Group of the currently logged in User. 
    + datePlayed (string, optional) - The date the game was played in yyyy-MM-dd format (e.g. 2015-04-29).
    + notes (string, optional) - Any notes or comments that the User wants to record about the game for future reference.
    + playerRanks (array[PlayerRank], required) - A collection of PlayerRank objects specifying the game rank and points scored for each Player. See below table for details.
    + applicationLinkages (array[ApplicationLinkage], optional) - A collection of ApplicationLinkage objects specifying external identifiers for the Played Game in other systems. Should always have at least one ApplicationLinkage with applicationName = "NemeStats" and entityId = "{NemeStats Played Game Id}".

+ Request Valid Request (application/json)

    + Headers
            
            X-Auth-Token: some token
            
    + Body

                {
                  "gameDefinitionId" : 1234,
                  "gamingGroupId" : 9818
                  "datePlayed" : "2015-04-05",
                  "notes" : "Erica destroyed us with her harpy shoes of the bear-goddess",
                  "playerRanks" : [ 
                      { 
                        "playerId" : 456, 
                        "gameRank" : 1, 
                        "pointsScored" : 15 
                      }, 
                      { 
                        "playerId" : 678, 
                        "gameRank" : 2, 
                        "pointsScored" : 13 
                      }, 
                      { 
                        "playerId" : 356, 
                        "gameRank" : 3, 
                        "pointsScored" : 9 
                      },
                      { 
                        "playerId" : 9175, 
                        "gameRank" : 3, 
                        "pointsScored" : 9 
                      }
                  ],
                  "applicationLinkages" : [
                      {
                        "applicationName" : "BGG",
                        "entityId" : "18839193"
                      },
                      {
                        "applicationName" : "BGStats",
                        "entityId" : "6b71050d-e63e-41a1-a476-399b7103f127"                      
                      }
                  ]
                }

+ Response 200 (application/json)

                {
                  "playedGameId" : 31995,
                  "gamingGroupId" : 9818
                }

+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }
                
+ Response 401 (application/json)

                {
                    "message" : "User with Id '8ba1050d-e6ee-41a1-a476-399b7103f219' does not have access to entity of type 'GamingGroup' with Id '9818'"
                }               

+ Response 401 (application/json)

                {
                    "message" : "User with Id '8ba1050d-e6ee-41a1-a476-399b7103f219' does not have access to entity of type 'GameDefinition' with Id '1234'"
                }  
                
+ Response 409 (application/json)

                {
                    "message" : "Player with id '456' is not in the Gaming Group with id '1351' -- which is the Gaming Group to which the Played Game is being recorded. All Players must be in this Gaming Group."
                }

+ Response 409 (application/json)

                {
                    "message" : "An entity with an ApplicationName of 'BGG' and an ExternalSourceEntityId of '18839193' already exists in the Gaming Group with id '9818'."
                }

## Update an existing Played Game [PUT]
This service will update an existing PlayedGame and will recalculate any Badges or Achievements accordingly.

+ Attributes
    + playedGameId (number, required) - NemeStats unique identifier for the Played Game to update.
    + gameDefinitionId (number, required) - NemeStats unique identifier for the Game Definition (e.g. Race For the Galaxy's unique Id) of the Played Game.
    + gamingGroupId (number, optional) - The NemeStats unique identifier for the Gaming Group where the Played Game will be logged. If no gamingGroupId is specified, the Played Game will remain in the same Gaming Group.
    + notes (string, optional) - Any notes or comments that the User wants to record about the game for future reference. This will overwrite any existing notes -- even if the new value would be empty.
    + playerRanks (array[PlayerRank], required) - A collection of PlayerRank objects specifying the game rank and points scored for each Player. See below table for details.
    + applicationLinkages (array[ApplicationLinkage], optional) - A collection of ApplicationLinkage objects specifying external identifiers for the Played Game in other systems. Should always have at least one ApplicationLinkage with applicationName = "NemeStats" and entityId = "{NemeStats Played Game Id}".

+ Request Valid Request (application/json)

    + Headers
            
            X-Auth-Token: some token
            
    + Body

                {
                  "playedGameId" : 591831
                  "gameDefinitionId" : 1234,
                  "gamingGroupId" : 9818
                  "datePlayed" : "2016-11-05",
                  "notes" : "Erica cheated."
                  "playerRanks" : [ 
                      { 
                        "playerId" : 456, 
                        "gameRank" : 1, 
                        "pointsScored" : 15 
                      }, 
                      { 
                        "playerId" : 678, 
                        "gameRank" : 2, 
                        "pointsScored" : 13 
                      }, 
                      { 
                        "playerId" : 356, 
                        "gameRank" : 3, 
                        "pointsScored" : 9 
                      },
                      { 
                        "playerId" : 9175, 
                        "gameRank" : 3, 
                        "pointsScored" : 9 
                      }
                  ],
                  "applicationLinkages" : [
                      {
                        "applicationName" : "BGG",
                        "entityId" : "18839193"
                      },
                      {
                        "applicationName" : "BGStats",
                        "entityId" : "6b71050d-e63e-41a1-a476-399b7103f127"                      
                      }
                  ]
                }

+ Response 204 (application/json)


+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }

+ Response 401 (application/json)

                {
                    "message" : "User with Id '8ba1050d-e6ee-41a1-a476-399b7103f219' does not have access to entity of type 'PlayedGame' with Id '591831'"
                }  
                
+ Response 401 (application/json)

                {
                    "message" : "User with Id '8ba1050d-e6ee-41a1-a476-399b7103f219' does not have access to entity of type 'GamingGroup' with Id '9818'"
                }               

+ Response 401 (application/json)

                {
                    "message" : "User with Id '8ba1050d-e6ee-41a1-a476-399b7103f219' does not have access to entity of type 'GameDefinition' with Id '1234'"
                }  
                
+ Response 401 (application/json)

                {
                    "message" : "User with Id '8ba1050d-e6ee-41a1-a476-399b7103f219' does not have access to entity of type 'Player' with Id '456'"
                }  
                
+ Response 404 (application/json)

                {
                    "message" : "Entity of type 'PlayedGame' with Id '591831' does not exist."
                }
                
+ Response 409 (application/json)

                {
                    "message" : "Player with id '456' is not in the Gaming Group with id '9818' -- which is the Gaming Group to which the Played Game is being recorded. All Players must be in this Gaming Group."
                }

+ Response 409 (application/json)

                {
                    "message" : "An entity with an ApplicationName of 'BGG' and an ExternalSourceEntityId of '18839193' already exists in the Gaming Group with id '9818'."
                }


## Get Played Games [GET /PlayedGames/{?gamingGroupId,startDateGameLastUpdated,endDateGameLastUpdated,datePlayedFrom,datePlayedTo,playerId,maximumNumberOfResults,exclusionApplicationName,inclusionApplicationName}] 
Retrieve a list of Played Games given some criteria. Currently limited to a single Gaming Group at a time
via the required gamingGroupId query string parameter.

+ Parameters
    + gamingGroupId : 923 (number, required) - The NemeStats unique identifier for the Gaming Group of the Played Game.
    + startDateGameLastUpdated : `2015-04-26` (string, optional) - If set, all Played Games returned will have been updated greater than or equal to this date. Dates must be in yyyy-MM-dd format.
    + endDateGameLastUpdated : `2015-09-30` (string, optional) - If set, all Played Games returned will have been updated less than or equal to this date. Dates must be in yyyy-MM-dd format.
    + datePlayedFrom : `2015-07-01` (string, optional) - If set, all Played Games returned will returned will have been played greater than or equal to this date. Dates must be in yyyy-MM-dd format.
    + datePlayedTo : `2015-07-15` (string, optional) - If set, all Played Games returned will have been played less than or equal to this date. Dates must be in yyyy-MM-dd format.
    + playerId: 9791 (number, optional) - If set, will only return Played Games where this Player participated.
    + exclusionApplicationName (string, optional) - If set, only returns Played Games where there are no Application Linkages with an applicationName matching the specified value. This could be useful for finding any Played Games that did not original from a particular client application. Used in conjuction with startDateGameLastUpdated it could be especially useful for mass synching.
    + inclusionApplicationName (string, optional) - If set, only returns Played Games where there is an Application Linkage having the specified value. This could be useful for finding any Played Games that originated from the source application so that the unsynched games could be determined on the client side.
    + maximumNumberOfResults : 100 (number, optional) - The maximum number of results to be returned. The default is no limit.
        + Default: 1000000
    
+ Request ValidRequest (application/json)
    + Headers
            
            X-Auth-Token: some token
            
+ Response 200 (application/json)

            {  
                "playedGames":[
                    {  
                        "playerGameResults":[  
                            {  
                                "playerId":1,
                                "playerName":"Dave Staw",
                                "gameRank":1,
                                "pointsScored":15,
                                "nemeStatsPointsAwarded":19,
                                "gameDurationBonusNemePoints" : 38,
                                "gameWeightBonusNemePoints" : 4,
                                "totalNemeStatsPointsAwarded" : 61
                            },
                            {  
                                "playerId":7,
                                "playerName":"Redeish",
                                "gameRank":2,
                                "pointsScored":null,
                                "nemeStatsPointsAwarded":11,
                                "gameDurationBonusNemePoints" : 22,
                                "gameWeightBonusNemePoints" : 3,
                                "totalNemeStatsPointsAwarded" : 36
                            },
                            {  
                                "playerId":6,
                                "playerName":"Mike Kochel",
                                "gameRank":3,
                                "pointsScored":9,
                                "nemeStatsPointsAwarded":6,
                                "gameDurationBonusNemePoints" : 12,
                                "gameWeightBonusNemePoints" : 3,
                                "totalNemeStatsPointsAwarded" : 21
                            },
                            {  
                                "playerId":5,
                                "playerName":"Gooseman",
                                "gameRank":3,
                                "pointsScored":9,
                                "nemeStatsPointsAwarded":6,
                                "gameDurationBonusNemePoints" : 12,
                                "gameWeightBonusNemePoints" : 3,
                                "totalNemeStatsPointsAwarded" : 21
                            }
                        ],
                        "applicationLinkages": [
                            {
                                "applicationName": "NemeStats",
                                "entityId": "16785"
                            },
                            {
                                "applicationName": "app2",
                                "entityId": "app1EntityId2"
                            },
                            {
                                "applicationName": "app3",
                                "entityId": "app3EntityId3"
                            }
                      ]
                        "playedGameId":16785,
                        "gameDefinitionId":1,
                        "gameDefinitionName":"Small World",
                        "gamingGroupId":1,
                        "gamingGroupName":"RIDGID Board Gamers",
                        "notes":"Dave Staw ran away with this one!",
                        "boardGameGeekObjectId":40692,
                        "datePlayed":"2015-04-04",
                        "dateLastUpdated":"2015-04-24"
                    },
                    {  
                        "playerGameResults":[  
                            {  
                                "playerId":11,
                                "playerName":"Charles Cai",
                                "gameRank":2,
                                "pointsScored":null,
                                "nemeStatsPointsAwarded":2,
                                "gameDurationBonusNemePoints" : 0,
                                "gameWeightBonusNemePoints" : 0,
                                "totalNemeStatsPointsAwarded" : 2
                            },
                            {  
                                "playerId":1018,
                                "playerName":"Marcus",
                                "gameRank":2,
                                "pointsScored":null,
                                "nemeStatsPointsAwarded":2,
                                "gameDurationBonusNemePoints" : 0,
                                "gameWeightBonusNemePoints" : 0,
                                "totalNemeStatsPointsAwarded" : 2
                            },
                            {  
                                "playerId":9,
                                "playerName":"Tosho",
                                "gameRank":2,
                                "pointsScored":null,
                                "nemeStatsPointsAwarded":2,
                                "gameDurationBonusNemePoints" : 0,
                                "gameWeightBonusNemePoints" : 0,
                                "totalNemeStatsPointsAwarded" : 2
                            }
                        ],
                        "applicationLinkages": [
                            {
                                "applicationName": "NemeStats",
                                "entityId": "16098"
                            }
                        ]
                        "playedGameId":16098,
                        "gameDefinitionId":7720,
                        "gameDefinitionName":"Dead of Winter: A Crossroads Game (2014)",
                        "gamingGroupId":1,
                        "gamingGroupName":"RIDGID Board Gamers",
                        "boardGameGeekObjectId":150376,
                        "datePlayed":"2015-03-06T00:00:00",
                        "dateLastUpdated":"2015-03-06T18:11:17.33"
                    }
                ]
            }

+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }

## Delete an existing Played Game [DELETE /PlayedGames/{playedGameId}/]
This service will permanently delete a Played Game and re-adjust NemeStats statistics accordingly.

+ Parameters
    + playedGameId : 16098 (number, required) - The NemeStats unique identifier of a given Played Game.

+ Request Valid Request (application/json)

    + Headers
            
            X-Auth-Token: some token

+ Response 204
                
+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }
                
+ Response 404 (application/json)

                {
                    "message" : "A Played Game with playedGameId '-1' does not exist in this Gaming Group."
                } 
                
# Players [/Players/]
A Player represents a person in a Gaming Group. A Player must be created to log games for that person. If a given person is in multiple
Gaming Groups, a new Player will be created for each Gaming Group. A Player may or may not be associated with a registered User.

+ Attributes
    + playerId (number, required) - The NemeStats unique identifier for the Player.
    + playerName (string, required) - The name of the Player in this Gaming Group.
    + gamingGroupId (number, required) - The NemeStats unique identifier for the Gaming Group to which this Player belongs.
    + nemesisPlayerId (number, optional) - The NemeStats unique identifier for the Player who is this Player's Nemesis. The Nemesis is the Player who has the highest win percentage vs. this Player and who has won at least 3 games.
    + active (boolean, required) - Flag indicating whether the Player is active or inactive. Inactive Players will not show up in the NemeStats website.

## Get Players in Gaming Group [GET /Players/{?gamingGroupId}] 
Retrieve a list of all Players in the given Gaming Group.

+ Parameters
    + gamingGroupId : 923 (number, required) - The NemeStats unique identifier for the Gaming Group of the Player.

+ Request ValidRequest (application/json)
    + Headers
            
            X-Auth-Token: some token
            
+ Response 200 (application/json)

                {
                  "players" : [
                        {
                            "playerName" : "Anna Viko",
                            "playerId" : 789,
                            "active" : "true",
                            "currentNemesisPlayerId" : 456
                        },
                        {
                            "playerName" : "Chris Konnel",
                            "playerId" : 456,
                            "active" : "true",
                            "currentNemesisPlayerId" : 456
                        },
                        {
                            "playerName" : "The Destroyer",
                            "playerId" : 111,
                            "active" : "true",
                            "currentNemesisPlayerId" : null
                        },
                        {
                            "playerName" : "Herb",
                            "playerId" : 112,
                            "active" : "true",
                            "currentNemesisPlayerId" : 789
                        },
                        {
                            "playerName" : "Marvin",
                            "playerId" : 745,
                            "active" : "false",
                            "currentNemesisPlayerId" : null
                        }
                    ]
                }

+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }

## Create a new Player [POST]
This service will create a new Player in the specified Gaming Group (per the gamingGroupId).

+ Attributes
    + playerName (string, required) - The name of the Player in this Gaming Group.
    + gamingGroupId (number, optional) - The NemeStats unique identifier for the Gaming Group where the Player will be created. If no gamingGroupId is specified, the Player will be created under the default Gaming Group of the currently logged in User.


+ Request Valid Request (application/json)
    + Headers
            
            X-Auth-Token: some token
    + Body
    
                {
                  "playerName" : "Some Sweet Player Name That Is Unique In This Gaming Group"
                }

+ Response 200 (application/json)

                {
                  "playerId" : 105156
                }

+ Request Invalid Request Where Player Already Exists (application/json)
    + Headers
            
            X-Auth-Token: some token
    + Body
    
                {
                  "playerName" : "Some Player Name That Already Exists In The Gaming Group"
                }               

                
+ Response 409 (application/json)

                {
                    "message" : "A Player with name 'Some Player Name That Already Exists In The Gaming Group' already exists in this Gaming Group. The existing playerId is '15490'."
                }
                
+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }
                
## Update an existing Player [PUT /Players/{playerId}/]
This service will update a given Player in the given Gaming Group.

+ Parameters
    + playerId : 12345 (number, required) - The NemeStats unique identifier of a given Player.

+ Attributes
    + playerName (string, optional) - The name of the Player in this Gaming Group.
    + active (boolean, optional) - Flag indicating whether the Player should be marked as active or inactive. Inactive Players will not show up in the NemeStats website.

+ Request Valid Request (application/json)

    + Headers
            
            X-Auth-Token: some token

    + Body
    
                {
                  "playerName" : "Some Sweet Player Name That Is Unique In This Gaming Group",
                  "active" : "true"
                }

+ Response 204

+ Request Invalid Request Name Already Exists (application/json)

    + Headers
            
            X-Auth-Token: some token
    + Body
    
                {
                  "playerName" : "Some Player Name That Already Exists In The Gaming Group"
                }               

                
+ Response 400 (application/json)

                {
                    "message" : "A Player with name 'Some Player Name That Already Exists In The Gaming Group' already exists in this Gaming Group."
                }

                
+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }
                
+ Response 404 (application/json)

                {
                    "message" : "A Player with playerId '12345' does not exist in this Gaming Group."
                } 
                
# Game Definitions [/GameDefinitions/]
A Game Definition represents a unique game (e.g. Race For The Galaxy, Candy Land, Axis and Allies, etc.) in a Gaming Group.
Game Definitions may be linked with Board Game Geek (BGG) to facilitate integration with that site and to bring together
a common unique identifier for board games across different Gaming Groups.

+ Attributes
    + gameDefinitionId (number, required) - NemeStats unique identifier for the given Game Definition.
    + gamingGroupId (number, required) - The NemeStats unique identifier for the Gaming Group of the Game Definition.
    + gameDefinitionName (string, required) - Name of the Game Definition (e.g. 'Monopoly) within the given Gaming Group.
    + boardGameGeekObjectId (number, optional) - Board Game Geek unique identifier for the Game Definition. Used to conveniently cross reference with Board Game Geek.
    + active (boolean, required) - Flag indicating whether or not the Game Definition is still active within the Gaming Group. Inactive Game Definitions will nto show up in the NemeStats website.

## Get Game Definitions in Gaming Group [GET /GameDefinitions/{?gamingGroupId}] 
Retrieve a list of all Game Definitions in the given Gaming Group.

+ Parameters
    + gamingGroupId : 923 (number, required) - The NemeStats unique identifier for the Gaming Group of the Game Definitions.

+ Request ValidRequest (application/json)
    + Headers
            
            X-Auth-Token: some token
            
+ Response 200 (application/json)

                {
                  "gameDefinitions" : [
                    {
                        "gameDefinitionName" : "Zombicide",
                        "gameDefinitionId" : 711,
                        "boardGameGeekObjectId" : 113924,
                        "active " : "true"
                    },
                    {
                        "gameDefinitionName" : "Candy Land",
                        "gameDefinitionId" : 12,
                        "active " : "true"
                    },
                    {
                        "gameDefinitionName" : "Small World",
                        "gameDefinitionId" : 789,
                        "boardGameGeekObjectId" : 40692,
                        "active " : false
                    }
                }

+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }

## Create a new Game Definition [POST]
This service will create a new Game Definition in the specified Gaming Group (per the gamingGroupId).

+ Attributes
    + gameDefinitionName (string, required) - The name of the Game Definition in this Gaming Group.
    + gamingGroupId (number, optional) - The NemeStats unique identifier for the Gaming Group where the Game Definition will be created. If no gamingGroupId is specified, the Game Definition will be created under the default Gaming Group of the currently logged in User.
    + gameDefinitionDescription (string, optional) - Description of the Game Definition.
    + boardGameGeekObjectId (number, optional) - The Board Game Geek unique identifier for the Game. 

+ Request Valid Request (application/json)
    + Headers
            
            X-Auth-Token: some token
    + Body
    
                {
                  "gameDefinitionName" : "Some Sweet Game Definition Name That Is Unique In This Gaming Group",
                  "boardGameGeekObjectId" : 199185,
                  "gamingGroupId" : 195
                }

+ Response 200 (application/json)

                {
                  "gameDefinitionId" : 105156,
                  "gamingGroupId" : 195
                }
                
+ Response 409 (application/json)

                {
                  "message" : "A Game Definition with name 'Monopoly (1933)' already exists in this Gaming Group."
                }
                
## Update an existing Game Definition [PUT /GameDefinitions/{gameDefinitionId}/]
This service will update a given Player in the given Gaming Group.

+ Parameters
    + gameDefinitionId : 923 (number, required) - The NemeStats unique identifier of a given Game Definition.

+ Attributes
    + gameDefinitionName (string, optional) - The name of the Game Definition in this Gaming Group.
    + active (boolean, optional) - Flag indicating whether the Game Definition should be marked as active or inactive. Inactive Game Definitions will not show up in the NemeStats website.

+ Request Valid Request (application/json)
    + Headers
            
            X-Auth-Token: some token
    + Body
    
                {
                  "gameDefinitionName" : "Some Sweet Game Definition Name That Is Unique In This Gaming Group",
                  "active" : "true"
                }

+ Response 204

+ Request Invalid Request Name Already Exists (application/json)
    + Headers
            
            X-Auth-Token: some token
    + Body
    
                {
                  "gameDefinitionName" : "Some Game Definition Name That Already Exists In The Gaming Group"
                }               

                
+ Response 400 (application/json)

                {
                    "message" : "A Game Definition with name 'Some Game Definition Name That Already Exists In The Gaming Group' already exists in this Gaming Group."
                }

                
+ Response 400 (application/json)

                {
                    "message" : "This action requires an X-Auth-Token header."
                }

+ Response 401 (application/json)

                {
                    "message" : "Invalid X-Auth-Token"
                }
                
+ Response 404 (application/json)

                {
                    "message" : "A Game Definition with gameDefinitionId '87658' does not exist in this Gaming Group."
                }