[IMAGE: https://hackmd.io/_uploads/rJTzc4BIp.jpg]
This post is intended for all you Splinterlands community developers out there.
With Rebellion Conflicts coming soon, and already available for testing on the Mavs QA server, I figured it's time to go over the details of API additions that have been made to support this new airdrop mechanism.
Note that the following changes will not go live for the real game until Conflicts is released, but you can try them all out now in Mavs QA. All example links are for Mavs QA; for the real game you would replace api.mavs-sl.com with api.splinterlands.com
Conflict Seasons
Conflicts are organized into a series of 9 roughly monthly events, which internally are known as Conflict Seasons (analogous to Ranked Play Seasons). There is an End-Of-Conflict (EOC) process, after which the Airdrop Card for that particular Conflict becomes claimable. The next Conflict Season begins immediately after the previous one finishes. At EOC, all cards & packs that players have staked will automatically carry over to the next Conflict Season, but contribution points will be reset and start accumulating from 0 again.
cards/collection
cards/collection_by_card
These APIs will have a wagon_uid field added to the data for each card, which will be set if that particular card is staked on a Mage Wagon. If the card is not staked, wagon_uid will be null.
Examples:
- https://api.mavs-sl.com/cards/collection/nebulusx
- https://api.mavs-sl.com/cards/collection_by_card?player=nebulusx&card_detail_id=648
conflicts/seasons
Fetches data about Conflict Seasons. Note that various fields for future Conflict Seasons that have not started yet may be null or set with dummy data, until such time as that season is about to start. We don't have all 9 Airdrop Cards finalized yet.
Examples:
- https://api.mavs-sl.com/conflicts/seasons - returns all Conflict Season records, including data for future Conflicts that have not started yet.
- https://api.mavs-sl.com/conflicts/seasons?id=current - returns data for the current Conflict Season, or an error message if there isn’t one.
- https://api.mavs-sl.com/conflicts/seasons?id=2 - returns data for a specific numbered Conflict Season. id must be > 0
conflicts/players
Returns data about players participating in particular Conflict Seasons, including contribution points towards the Conflict and Airdrop Cards won in completed Conflicts, if any.
Note that if not explicitly specified with optional parameters, by default airdrop data is not included and the sort order will be reward_points DESC, player ASC
Examples:
- https://api.mavs-sl.com/conflicts/players - return data for the current Conflict Season (or an error if there is no Conflict currently active).
- https://api.mavs-sl.com/conflicts/players?id=1 - return data for the indicated Conflict Season (in this case, the season with Conflict ID 1). This is a required parameter if all Conflict Seasons have completed (i.e. if there is no Conflict currently active).
- https://api.mavs-sl.com/conflicts/players?conflict=1 - optional flag, adds extra data about the targeted Conflict Season.
- https://api.mavs-sl.com/conflicts/players?airdrop_data=1 - optional flag, includes fields for airdrop data.
- https://api.mavs-sl.com/conflicts/players?non_zero_rp=1 - optional flag, indicates that only data for which reward_points > 0 should be included.
- https://api.mavs-sl.com/conflicts/players?player=davemccoy - optional parameter, returns data for only the indicated player. If the airdrop_data flag is also being used, then extra information about the number of airdrop cards awarded to this player will be added (if the Conflict Season in question has completed!).
- https://api.mavs-sl.com/conflicts/players?order_by=reward_points:DESC,progress_to_next:DESC,player:ASC - overrides the default sort order. Must be in the format shown, and capitalization is important. This example will get turned into
ORDER BY reward_points DESC, progress_to_next DESC, player ASCand any number of columns / fields can be included. - https://api.mavs-sl.com/conflicts/players?id=2&conflict=1&airdrop_data=1&non_zero_rp=1&order_by=player:ASC - this example shows that all the various parameters can be combined in whatever way desired.
Notes about meaning of player data fields:
[IMAGE: https://hackmd.io/_uploads/SJngJUrL6.png]
- reward_point_threshold = how much reward progress must be made to earn a single Airdrop Chance
- reward_points = this is the number of Airdrop Chances that have been earned by this player for the Conflict Season in question.
- progress_to_next = how much reward progress has been made so far towards the next Airdrop Chance. When this reaches reward_point_threshold, it will reset to 0 and the player's reward_points will go up by 1
- last_rp_update = timestamp of the last time a player's reward progress was saved to the back-end database. There is a Reward Point Updater process that will save data every hour. Data also gets updated whenever a player makes a change to cards or packs staked for Conflicts.
- rp_per_hour = reward progress per hour; this is the sum total of Collection Power of a player's staked cards on all Mage Wagons + contribution from staked Rebellion packs. It indicates how much reward progress accrues towards the next Airdrop Chance every hour. For example, if reward_point_threshold = 100000 and rp_per_hour = 200000, then reward_points will increment by 2 for every hour that passes.
Alternative usage for multiple Conflict Seasons:
- https://api.mavs-sl.com/conflicts/players?player=davemccoy&mode=all_conflicts - use the mode parameter to indicate you want data for a single player across all Conflict Seasons. This usage requires that player be set, and disallows all of the other optional parameters (except uids, see below). The sort order used is
conflict_season ASC. This mode adds extra information about each Conflict Season and the number of airdrop cards awarded in the distribution for completed Conflict Seasons. This information, together, can be used to determine if a player has any outstanding Conflicts airdrops that need to be claimed.
uids parameter:
An optional parameter that can be combined with the player and mode parameters. Has no effect if you are retrieving data for all players. This will add a list of uids for airdrop cards received. It’s the most data intensive type of querying, so should be used sparingly.
Examples:
- https://api.mavs-sl.com/conflicts/players?player=nebulusx&mode=all_conflicts&uids=1
- https://api.mavs-sl.com/conflicts/players?id=1&player=nebulusx&airdrop_data=1&uids=1
conflicts/airdrop_distribution
Returns airdrop distribution data for completed Conflicts, showing how many cards were awarded to each player. Note that this data does not indicate what proportion of cards are regular foil vs gold foil; for that you need to look at the airdrop claim data from the conflicts/players API.
Also, the default sort order of results is num_prizes DESC, player ASC
Examples:
- https://api.mavs-sl.com/conflicts/airdrop_distribution - return data for the most recently completed Conflict Season, or an error if there are no completed Conflict Seasons.
- https://api.mavs-sl.com/conflicts/airdrop_distribution?id=1 - return data for the indicated Conflict Season, or an error if the indicated Conflict Season has not yet completed.
- https://api.mavs-sl.com/conflicts/airdrop_distribution?conflict=1 - optional flag, adds extra data about the targeted Conflict Season.
- https://api.mavs-sl.com/conflicts/airdrop_distribution?player=nebulusx - optional parameter, returns data for only the indicated player
- https://api.mavs-sl.com/conflicts/airdrop_distribution?order_by=num_prizes:DESC,player:ASC - overrides the default sort order. Must be in the format shown, and capitalization is important. This example will get turned into
ORDER BY num_prizes DESC, player ASCand any number of columns / fields can be included. - https://api.mavs-sl.com/conflicts/airdrop_distribution?id=1&conflict=1&order_by=player:DESC - this example shows that all the various parameters can be combined in whatever way desired.
Alternative usage for multiple Conflict Seasons:
- https://api.mavs-sl.com/conflicts/airdrop_distribution?player=nebulusx&mode=all_conflicts - use the mode parameter to indicate you want data for a single player across all Conflict Seasons. This usage requires that player be set, and disallows all of the other optional parameters except for order_by, which can still be used. The default sort order is
conflict_season ASC
conflicts/leaderboard
Used to get leaderboard data on top players for a given Conflict Season. Note that for the current Conflict, leaderboard data will only be updated once per hour, or for individual players whenever that player makes a changes to staked Rebellion cards or packs.
Leaderboard data is limited to the top 200 players, but does also include a totals.total_reward_points field that indicates the total Airdrop Chances that have accumulated for all players participating in the given Conflict Season.
Examples:
- https://api.mavs-sl.com/conflicts/leaderboard - return data for the current Conflict Season (or an error if there is no Conflict currently active).
- https://api.mavs-sl.com/conflicts/leaderboard?id=1 - return data for the indicated Conflict Season (in this case, the season with Conflict ID 1). This is a required parameter if all Conflict Seasons have completed (i.e. if there is no Conflict currently active).
conflicts/leaderboard_with_player
Used to get an individual player’s leaderboard position for a given Conflict Season.
Examples:
- https://api.mavs-sl.com/conflicts/leaderboard_with_player?username=nebulusx - return data about the indicated player for the current Conflict Season (or an error if there is no Conflict currently active).
- https://api.mavs-sl.com/conflicts/leaderboard_with_player?username=nebulusx&id=1 - return data about the indicated player for a particular Conflict Season (in this case, the season with Conflict ID 1). Note that id is a required parameter if all Conflict Seasons have completed (i.e. if there is no Conflict currently active).
conflicts/status
Fetches several different pieces of information about current Conflict status for a given player. Let's look at examples of each piece of information:
-
config = bits of static config data: [IMAGE: https://hackmd.io/_uploads/S1NLtUHIp.png]
-
conflict = info on the current Conflict Season (if any): [IMAGE: https://hackmd.io/_uploads/SkyOK8SUT.png]
-
stats = player specific info about pack & wagon staking: [IMAGE: https://hackmd.io/_uploads/B1sYK8SL6.png]
-
player = player specific contribution info for the current Conflict Season (if any): [IMAGE: https://hackmd.io/_uploads/HJ-oYLBIa.png]
-
wagons = a list of player owned Mage Wagons and cards staked on them (if any). If the player does not own any wagons, this will be an empty array
[]. The wagons array will always be sorted intotal_cp DESC, wagon_uid ASCorder: [IMAGE: https://hackmd.io/_uploads/SyRg5IrLa.png]
Parameters:
- username = player to fetch data for
- only_xxxx = flag to indicate you only want 1 of the above types of data. Must be set to 1 if used.
- exclude_xxxx = flag to indicate you want to exclude one of the above types of data. Must be set to 1 if used. Can have multiple exclusions.
The only_xxxx and exclude_xxxx parameters can be used to optimize query performance by eliminating unneeded information. If all 3 of wagons, player, and stats data are excluded, then the username parameter becomes optional.
Examples:
- https://api.mavs-sl.com/conflicts/status?username=nebulusx - fetch all data for player nebulusx
- https://api.mavs-sl.com/conflicts/status?username=nebulusx&only_stats=1 - only fetch stats data. You might do this query if you only want to check on pack staking data and don’t care about wagons, for example.
- https://api.mavs-sl.com/conflicts/status?only_conflict=1 - only fetch current Conflict Season data. In this case username is not needed.
- https://api.mavs-sl.com/conflicts/status?username=nebulusx&exclude_conflict=1&exclude_player=1&exclude_config=1 - exclude everything except for wagon & stats data
Note that if wagons data is included, then stats.total_wagon_cp will also be included, regardless of whether other stats are included or not.
conflicts/wagon
Returns information about assets staked on one particular wagon. Format of the return data is the same as the wagons data for the conflicts/status API above, but with the addition of a player field to indicate wagon ownership. Has one required parameter: uid
Example: https://api.mavs-sl.com/conflicts/wagon?uid=I-326-1MXYYBYC4W
conflicts/wagon_eligible_cards
Returns information about cards that are eligible to be placed on a player’s Battle Wagons. These cards will meet the following criteria:
- Card Set is Rebellion
- Card is not on the market
- Card is not delegated / rented out
- Card is not already staked on a Mage Wagon
- Card is not staked on Land
Parameters:
- username = player to fetch data for
- max_group_size = integer >= 1 that represents the max number of card UIDs that should be returned for a given grouping. This is optional; if not included, then all card UIDs will be returned. You may wish to use this parameter to reduce the size of the return data, if the UIDs of the cards are not important for your use case.
A grouping represents all card UIDs that have the same Collection Power, Card Detail ID, Gold, and BCX values. Note that even if max_group_size is used, a grouping’s qty field will be set to the total number of card UIDs that exist in that group. Groups will always have the following ordering: collection_power DESC, card_detail_id ASC, gold DESC, bcx DESC
Within a group, the list of card UIDs will be sorted in ascending alphabetical order.
Examples:
- https://api.mavs-sl.com/conflicts/wagon_eligible_cards?username=nebulusx - fetch & group all eligible cards for player nebulusx
- https://api.mavs-sl.com/conflicts/wagon_eligible_cards?username=nebulusx&max_group_size=5 - restrict the list of card UIDs for each group to no more than 5 cards each, regardless of the actual group size
[IMAGE: https://hackmd.io/_uploads/SktSywHUa.png]
Including flavor text (lore) in Conflict Season data:
An optional parameter lore=1 exists for the following APIs:
- conflicts/seasons
- conflicts/players
- conflicts/status
- conflicts/airdrop_distribution
This flag indicates that extra lore related fields should be included in Conflict Season data. If you don’t use it, then by default the following seasonal fields will not be included in API data:
- title
- sub_title
- description
- epilogue
- url
And that's it!
There you have it. Any questions about the above APIs can be referred to myself. Happy coding!