Player

Method: create

Authorization is required. In order to calculate changes and process events for an user, you need to FIRST create its game profile in the system. This is done by using this method

Request

HTTP request

POST https://<YOUR_DOMAIN>/rest/v1/en_US/player

Parameters

Do not supply a request parameters with this method.

Request body

property value description
id guid What should be the players Id in game system. This Id should be later sent with all events performed by this user
name string What should be the players human readable username in the game system.

Response

If successful, this method returns a response JSON with the following structure:

{
  "timestamp": "2014-03-03T23:20:23Z",
  "success": false,
  "message": "Aliqua anim consequat amet cupidatat proident amet amet.",
  "errors": [
    {
      "key": "name",
      "value": "",
      "message": "name is already taken"
    }
  ],
 "object": {
    "id": "0ed40157-61c8-447e-87aa-744f579e4efa",
    "type": "player",
    "name": "Bob",
    "experience":0,
    "level":1,
    "levelStartExperience": 0,
    "levelEndExperience": 99,
    "isPublicProfile": false,
    "lastLogNotifation": "2014-03-03T23:20:23Z",
    "lastLogRead": "2014-03-03T23:20:23Z",
    "lastModified": "2014-03-03T23:20:23Z",
    "quests": [],
    "cards": [],
    "log":[],
    "accessWarnings": []
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

property value description
success Boolean Whether the requested operation is successful or not
message String Human readable error information
errors List (object) List of validation errors, if any. The "key" property value is matched to one of the record's fields
object object The object that caused the validation errors or that was created. Have in mind that, if the server requires string trimming or data manipulation after the user submission, it is applied in this object. In this way the returned object can differe from the posted one.
id integer The player Id
name string Human readable name of the player
experience integer how many experience points has the player up till now.
level integer Based on the experience points and the formula presented in the game engine settings, what is the current level of the player
levelStartExperience integer On how many experience points the current player's level start. Used when presenting progress bar.
levelEndExperience integer On how many experience points the current player's level end. Used when presenting progress bar.
isPublicProfile boolean Whether the players profile should be presented to the public. This setting is per default false, but the user can change it.
lastLogNotifation date What is the last notification presented to the user in ISO 8601 date string and UTC time zone. Used to decide what notification needs to be presented to the user.
lastLogRead date When the player read its game log last. Used for presenting to the user, which log entries are new to him/her
lastModified date When the player profile was last modified in ISO 8601 date string and UTC time zone. Often used to decide whether a cache update is needed
card.id guid The Id of the card instance that is in the player's deck
card.cardId guid The Id of the card template from which was created this instance.
card.name string What is the card's name.
card.imageUrl string The URL to the card's image.
card.usageCount integer Do this card has any usage limitations. NULL for no limitations.
card.expiresOn date When the card should be removed from the player's deck in ISO 8601 date string and UTC time zone.
card.isEnabled boolean Can this card be used by the player. If not, there are some restrictions in the card settings that prevent him from using the card
card.costToRemove integer How many experience points costs to the player to remove the card. Can be negative, in which case the card removal will add points to the player's profile. If NULL the card cannot be removed from the player's deck.
card.features object A key/value list of the card's attributes as set in the game administration
quest.id guid The id of the quest instance that is received by the player
quest.questId guid The id of the quest template from which this instance was created
quest.name string The quest's name or title
quest.description string Some text/html of the quest, which is presented in the quest lists or reviews
quest.thumbImageUrl string URL of the quest thumbnail often used to represent the quest in the lists
quest.imageUrl string URL of the quest image that is often used to present the quest terms in more graphical way
quest.availableTo date The date to which the quest can be started in ISO 8601 date string and UTC time zone.
quest.expiresOn date The date to which the quest must be completed in ISO 8601 date string and UTC time zone.
quest.startedOn date The date on which the quest was started in ISO 8601 date string and UTC time zone.
quest.completedOn date The date on which the quest was completed in ISO 8601 date string and UTC time zone.
quest.failedOn date The date on which the quest failed in ISO 8601 date string and UTC time zone.
quest.rejectedOn date The date on which the quest was rejected in ISO 8601 date string and UTC time zone.
quest.rewardCardsCount integer How many cards are provided by the quest on successful completion
quest.experience integer How many experience points are provided by the quest on successful completion
quest.coins integer How many coins are provided by the quest on successful completion
quest.stateMessage string The state message text/html as generated by the system. Its template is defined in the quest settings.
card.features object A key/value list of the quest's attributes as set in the game administration
log.id guid Id of the log record
log.title string Title of the log record
log.description string Description of the log record
log.notification string What text/html should be presented in a screen notification or growl type alert. NULL if no message should be displayed
log.logType string Types can be: General, GameCardGained, GameCardLost, QuestSucceeded, QuestFailed, QuestStarted, QuestRejected, QuestAvailable, QuestUnavailable
log.experience integer Should the user be notified of any experience change with this log record
log.coins integer Should the user be notified of any coins change with this log record
log.isNew boolean Is this log record new for the user
log.isNotified boolean Was a screen growl alert/notification presented to the user
quest.createdOn date When this log record was created in ISO 8601 date string and UTC time zone.
quest.cards array of objects Should the user be notified of any card change with this record. The object properties are: id, cardId,name,imageUrl,isGained (whether the card was added or removed from the players deck)

Method: get

Authorization is required. Player is the game character of the user within the QListo system.

Request

HTTP request

GET https://<YOUR_DOMAIN>/rest/v1/en_US/player/{playerId}

Parameters

property value description
playerId guid The player's Id

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "success": true,
  "message": "Nisi proident tempor cillum sint duis eu elit dolor Lorem amet qui officia occaecat.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": [],
  "object": {
    "id": "0ed40157-61c8-447e-87aa-744f579e4efa",
    "type": "player",
    "name": "Bob",
    "experience":0,
    "level":1,
    "levelStartExperience": 0,
    "levelEndExperience": 99,
    "isPublicProfile": false,
    "lastLogNotifation": null,
    "lastLogRead": null,
    "lastModified": "2014-03-03T23:20:23Z",
    "quests": [
		{
			"id": "bcb8d2fc-46c5-4a61-b837-4aed4b50f72b",
			"questId": "fd6f235c-5072-4b7b-9bd9-8815ccd4ec01",
"type":"quest", "name": "Quest name", "description": "some description", "thumbImageUrl": "http://domain.com/gr/images/fd6f235c-5072-4b7b-9bd9-8815ccd4ec01/-8587956723534045808/quest-thumb.png", "imageUrl": "http://domain.com/gr/images/fd6f235c-5072-4b7b-9bd9-8815ccd4ec01/-8587956723534045808/quest-img.png", "availableTo": null, "expiresOn": null, "startedOn": "2014-12-10T14:25:51.227+02:00", "completedOn": null, "failedOn": null, "rejectedOn": null, "rewardCardsCount": 0, "experience": 0, "coins": 0, "stateMessage": null, "features": { "quest_reject_forbidden": "true" } } ], "cards": [ { "id": "d921ff51-7685-4c57-a7e8-07edfc21d6ac", "cardId": "5303990a-41aa-4c0a-98d1-93e29e329138",
"type":"card", "name": "card name", "imageUrl": "http://domain.com/gr/images/5303990a-41aa-4c0a-98d1-93e29e329138/-8588579733628245808/card.png", "usageCount": null, "expiresOn": null, "isEnabled": true, "costToRemove": null, "features": { "card_order_discount": "3", "card_present": "", "card_money_cash": "5", "card_block_auctions": "", "card_block_groupons": "", "card_block_reservations": "" } } ], "log":[ { "id": "bb9ef521-7b9f-4fc0-adbb-2851ed2d933a",
"type":"log", "title": "A quest was accepted", "description": "You have the wits, the strength and the experience. You can do it and now is the time.", "notification": null, "logType": "QuestStarted", "experience": null, "coins": null, "isNew": true, "isNotified": false, "createdOn": "2014-03-03T23:20:23Z", "cards": [] } ], "accessWarnings": [] } }

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

property value description
id integer The bookmark Id
group object Some common properties of the user that performed the action: id, name, slug, thumbUrl, url (of the group home page)
url string the record's URL field
description string The record's description field.
targetBlank boolean How to set up the target attribute of the bookmark link. If true, the link will be opened in a new browser's tab (target = "_blank")