Example command for running with Docker¶

    $ docker pull tfgco/donations
    $ docker run -t --rm -e "DONATIONS_MONGO_HOST=<mongoDB host>" -e "DONATIONS_MONGO_PORT=<mongoDB port>" -p 8080:8080 tfgco/donations

name¶

The name of your game. This is used mainly for easier reasoning of what this game is when debugging.

Type: string
Sample Value: My Sample Game

donationCooldownHours¶

Number of hours that must ellapse before a player can donate again. This is used in conjunction with the max donation weight passed in with the donation.

Type: Integer
Sample Value: 24

donationRequestCooldownHours¶

Number of hours a player must wait before requesting donations again.

Type: Int
Sample Value: 8

Creating/Updating an Item¶

The Update operation of the Item is idempotent (you can run it as many times as you want with the same result). If your item does not exist yet, it will create it, otherwise just updated it with the new configurations.

To Create/Update your item, just do a PUT request to http://my-donations-server/games/my-game-public-id/items/my-item-key, where my-game-public-id is the ID of the game you registered in the previous step and my-item-key is the item key you’ll be using in your game’s donation requests and donations in the future. The payload for the request is a JSON object in the body and should be as follows:

    {
      "metadata":                           [JSON],
      "weightPerDonation":                  [int],
      "limitOfItemsPerPlayerDonation":      [int],
      "limitOfItemsInEachDonationRequest":  [int]
    }

If the operation is successful, you’ll receive a JSON object with the item details.

Item Configuration Settings¶

As can be seen from the previous section, there are some configurations you can do per item. These will be thoroughly explained in this section.

metadata¶

This sections allow you to store metadata for this item.

Donations treats this as a black box and won’t use it for any operations. It will be returned whenever the item is returned, though.

Type: JSON
Sample Value: { "cost": 100, "currency": "gold" }

weightPerDonation¶

Donations keep track of the weight that has been donated by player in case you want to limit the max weight donated per player per time.

This configuration allows you to set different weights per donation per item (epic donations weigh more than rare and so on).

Type: int
Sample Value: 3

limitOfItemsPerPlayerDonation¶

The limit of items that can be donated by a single player for this item in a single donation request.

Type: int
Sample Value: 3

limitOfItemsInEachDonationRequest¶

The amount of this item that can be donated in a single donation request.

Type: int
Sample Value: 8

Healthcheck¶

GET /healthcheck

Validates that the app is still up, including the database connection.

• Success Response

  • Code: 200

  • Content:

      "WORKING"
    

• Error Response

  It will return an error if it failed to connect to the database.

  • Code: 500

  • Content:

      "Error connecting to database: <error-details>"
    

Update Game¶

PUT /games/:gameID

Updates the game with that has publicID gameID.

• Payload

  {
    "name":                          [string],  // 2000 characters max
    "donationCooldownHours":         [int],
    "donationRequestCooldownHours":  [int]
  }
  

• Success Response

  • Code: 200

  • Content:

    {
      "name":                          [string],  // 2000 characters max
      "donationCooldownHours":         [int],
      "donationRequestCooldownHours":  [int]
    }
    

• Error Response

  It will return an error if an invalid payload is sent or if there are missing parameters.

  • Code: 400

  • Content:

    {
      "success": false,
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "success": false,
      "reason": [string]
    }
    

Update Item¶

PUT /games/:gameID/items/:itemKey

Updates the item with key itemKey in the game with public ID gameID.

• Payload

  {
    "metadata":                           [JSON],
    "weightPerDonation":                  [int],
    "limitOfItemsPerPlayerDonation":      [int],
    "limitOfItemsInEachDonationRequest":  [int]
  }
  

• Success Response

  • Code: 200

  • Content:

    {
      "metadata":                           [JSON],
      "weightPerDonation":                  [int],
      "limitOfItemsPerPlayerDonation":      [int],
      "limitOfItemsInEachDonationRequest":  [int]
    }
    

• Error Response

  It will return an error if an invalid payload is sent or if there are missing parameters.

  • Code: 400

  • Content:

    {
      "success": false,
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "success": false,
      "reason": [string]
    }
    

Create Donation Request¶

POST /games/:gameID/donation-requests

Creates a new donation request for the item specified in the payload.

• Payload

  {
    "item":      [string],
    "player":    [string],
    "clan":      [string],
  }
  

  • item is the key for the item to create the donation request for;
  • player is the player id that will receive the donations;
  • clan is the team/clan/group the player belongs to. This is useful for grouping donations.

• Success Response

  • Code: 200
  • Content: Serialized donation request.

• Error Response

  It will return an error if an invalid payload is sent or if there are missing parameters.

  • Code: 400

  • Content:

    {
      "success": false,
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "success": false,
      "reason": [string]
    }
    

Donate to a Donation Request¶

POST /games/:gameID/donation-requests/:donationRequestID

Donates items to a donation request with public ID donationRequestID in the game gameID.

• Payload

  {
    "player":                 [string],
    "amount":                 [string],
    "maxWeightPerPlayer":     [string]
  }
  

  • player is the player id that will receive the donations;
  • amount is the quantity of the item being donated by this player;
  • maxWeightPerPlayer is the maximum weight this player can donate per time period.

• Success Response

  • Code: 200

  • Content:

    {
      "success": true
    }
    

• Error Response

  It will return an error if an invalid payload is sent or if there are missing parameters.

  • Code: 400

  • Content:

    {
      "success": false,
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "success": false,
      "reason": [string]
    }