def maps():
"""
Lists all map definitions.
**Example Request**:
.. sourcecode:: http
GET /maps
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"battle_type": "FFA",
"description": "<LOC canis3v3_Description>",
"display_name": "canis3v3",
"download_url": "http://content.faforever.com/faf/vault/maps/canis3v3.v0001.zip",
"downloads": 5970,
"id": "0",
"map_type": "skirmish",
"max_players": 6,
"num_draws": 0,
"rating": 2.94119,
"folder_name": "canis3v3.v0001",
"thumbnail_url_large": "http://content.faforever.com/faf/vault/map_previews/large/canis3v3.v0001.png",
"thumbnail_url_small": "http://content.faforever.com/faf/vault/map_previews/small/canis3v3.v0001.png",
"times_played": 1955,
"version": 1,
"author": "Someone"
},
"id": "0",
"type": "map"
},
...
]
}
"""
where = ''
args = None
many = True
filename_filter = request.values.get('filter[folder_name]')
if filename_filter:
where = ' filename = %s'
args = 'maps/' + filename_filter + '.zip'
results = fetch_data(MapSchema(), TABLE, SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request, where=where, args=args,
many=many, enricher=enricher)
return results
def maps():
"""
Lists all map definitions.
**Example Request**:
.. sourcecode:: http
GET /maps
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"battle_type": "FFA",
"description": "<LOC canis3v3_Description>",
"display_name": "canis3v3",
"download_url": "http://content.faforever.com/faf/vault/maps/canis3v3.v0001.zip",
"downloads": 5970,
"id": 0,
"map_type": "skirmish",
"max_players": 6,
"num_draws": 0,
"rating": 2.94119,
"technical_name": "canis3v3.v0001",
"thumbnail_url_large": "http://content.faforever.com/faf/vault/map_previews/large/maps/canis3v3.v0001.zip",
"thumbnail_url_small": "http://content.faforever.com/faf/vault/map_previews/small/maps/canis3v3.v0001.zip",
"times_played": 1955,
"version": "1"
},
"id": 0,
"type": "map"
},
...
]
}
"""
where = ''
args = None
many = True
filename_filter = request.values.get('filter[technical_name]')
if filename_filter:
where = ' filename = %s'
args = 'maps/' + filename_filter + '.zip'
many = False
results = fetch_data(MapSchema(), TABLE, SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request, where=where, args=args,
many=many, enricher=enricher)
return results
def laddermaps():
"""
Lists all maps of the current ladder map pool ( for 1v1)
**Example Request**:
.. sourcecode:: http
GET /maps/ladder1v1
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"battle_type": "FFA",
"description": "<LOC canis3v3_Description>",
"display_name": "canis3v3",
"download_url": "http://content.faforever.com/faf/vault/maps/canis3v3.v0001.zip",
"downloads": 5970,
"id": 0,
"map_type": "skirmish",
"max_players": 6,
"num_draws": 0,
"rating": 2.94119,
"folder_name": "canis3v3.v0001",
"thumbnail_url_large": "http://content.faforever.com/faf/vault/map_previews/large/maps/canis3v3.v0001.zip",
"thumbnail_url_small": "http://content.faforever.com/faf/vault/map_previews/small/maps/canis3v3.v0001.zip",
"times_played": 1955,
"version": 1
},
"id": 0,
"type": "map"
},
...
]
}
"""
LADDER_TABLE = "( {} ) JOIN ladder_map ON map.id = ladder_map.idmap".format(
TABLE)
results = fetch_data(MapSchema(),
LADDER_TABLE,
SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
enricher=enricher)
return results
def achievements_get(achievement_id):
"""
Gets an achievement definition.
**Example Request**:
.. sourcecode:: http
GET /achievement/02081bb0-3b7a-4a36-99ef-5ae5d92d7146
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"description": "Kill your enemy in a ranked 1v1 game in under 15 minutes",
"experience_points": 10,
"id": "02081bb0-3b7a-4a36-99ef-5ae5d92d7146",
"initial_state": "REVEALED",
"name": "Rusher",
"revealed_icon_url": "http://content.faforever.com/achievements/02081bb0-3b7a-4a36-99ef-5ae5d92d7146.png",
"total_steps": null,
"type": "STANDARD",
"unlocked_icon_url": "http://content.faforever.com/achievements/02081bb0-3b7a-4a36-99ef-5ae5d92d7146.png"
},
"id": "02081bb0-3b7a-4a36-99ef-5ae5d92d7146",
"type": "achievement"
}
}
:query string language: The preferred language to use for strings returned by this method. default is en.
:query string region: The preferred region to use for strings returned by this method. default is US.
:status 200: No error
:status 404: achievement
"""
language = request.args.get('language', 'en')
region = request.args.get('region', 'US')
return fetch_data(AchievementSchema(),
ACHIEVEMENTS_TABLE,
ACHIEVEMENT_SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
where='ach.id = %(id)s',
args={
'id': achievement_id,
'language': language,
'region': region
},
many=False)
def game(game_id):
result = fetch_data(GameStats(),
GAME_STATS_TABLE + MAP_JOIN + GAME_PLAYER_STATS_JOIN + GLOBAL_JOIN + LOGIN_JOIN +
FEATURED_MOD_JOIN, GAME_SELECT_EXPRESSIONS, MAX_GAME_PAGE_SIZE, request,
where='gs.id = %s', args=game_id, enricher=enricher, players=PLAYER_SELECT_EXPRESSIONS)
if len(result['data']) == 0:
return {'errors': [{'title': 'No game with this game ID was found'}]}, 404
return sort_game_results(result)
def list_bugreports():
"""
Lists all bug report definitions.
**Example Request**:
.. sourcecode:: http
GET /bugs
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"automatic": true,
"id": "31424",
"log": "log",
"target": {
"data": {
"attributes": {
"name": "client",
"ref": "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000",
"url": "https://github.com/FAForever/client"
},
"id": "client/tree/\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000",
"type": "bugreport_target"
}
},
"title": "Bug report",
"traceback": "traceback"
},
"id": "31424",
"type": "bugreport"
},
...
]
}
:status 200: No error
"""
def add_bugreport_target(item):
item['target'] = {
'name': item['name'],
'ref': item['ref'],
'url': item['url']
}
return fetch_data(BugReportSchema(), TABLE, SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request, enricher=add_bugreport_target)
def ranked1v1_get(player_id):
"""
Gets a ranked player. Player must be active, played more than one ranked game, and must have statistics associated
with he/she.
**Example Request**:
.. sourcecode:: http
GET /ranked1v1/781
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"deviation": 48.4808,
"id": "781",
"is_active": true,
"login": "******",
"mean": 2475.69,
"num_games": 1285,
"ranking": 1,
"rating": 2330,
"won_games": 946
},
"id": "781",
"type": "ranked1v1"
}
}
:status 200: No error
:status 404: No entry with this id was found
"""
select_expressions = SELECT_EXPRESSIONS.copy()
select_expressions['ranking'] = """(SELECT count(*) FROM ladder1v1_rating
WHERE ROUND(mean - 3 * deviation) >= ROUND(r.mean - 3 * r.deviation)
AND is_active = 1
AND numGames > 0)
"""
result = fetch_data(Ranked1v1Schema(), TABLE, select_expressions, MAX_PAGE_SIZE, request,
many=False, where='r.id=%(id)s', args=dict(id=player_id, row_num=0))
if 'id' not in result['data']:
return {'errors': [{'title': 'No entry with this id was found'}]}, 404
return result
def achievements_list():
"""
Lists all achievement definitions.
**Example Request**:
.. sourcecode:: http
GET /achievements
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"description": "Kill your enemy in a ranked 1v1 game in under 15 minutes",
"experience_points": 10,
"id": "02081bb0-3b7a-4a36-99ef-5ae5d92d7146",
"initial_state": "REVEALED",
"name": "Rusher",
"revealed_icon_url": "http://content.faforever.com/achievements/02081bb0-3b7a-4a36-99ef-5ae5d92d7146.png",
"total_steps": null,
"type": "STANDARD",
"unlocked_icon_url": "http://content.faforever.com/achievements/02081bb0-3b7a-4a36-99ef-5ae5d92d7146.png",
"unlockers_count": 416,
"unlockers_percent": 0.49,
"unlockers_min_duration": 1000,
"unlockers_avg_duration": 2000,
"unlockers_max_duration": 3000
},
"id": "02081bb0-3b7a-4a36-99ef-5ae5d92d7146",
"type": "achievement"
},
...
]
}
:query string language: The preferred language to use for strings returned by this method. default is en.
:query string region: The preferred region to use for strings returned by this method. default is US.
:status 200: No error
"""
language = request.args.get('language', 'en')
region = request.args.get('region', 'US')
sort = request.args.get('sort', 'order')
return fetch_data(AchievementSchema(), ACHIEVEMENTS_TABLE, ACHIEVEMENT_SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request,
args={'language': language, 'region': region}, sort=sort)
def events_list_player(player_id):
"""
Lists the events for a player.
**Example Request**:
.. sourcecode:: http
GET /players/781/events
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"id": string,
"attributes": {
"event_id": string,
"count": integer,
"create_time": long,
"update_time": long
}
}
]
}
:status 200: No error
"""
select_expressions = copy(PLAYER_EVENTS_SELECT_EXPRESSIONS)
del select_expressions['player_id']
where = 'player_id = %s'
args = tuple([player_id])
id_filter = request.values.get('filter[event_id]')
if id_filter:
ids = id_filter.split(',')
where += ' AND event_id IN ({})'.format(','.join(['%s'] * len(ids)))
args += tuple(ids)
return fetch_data(PlayerEventSchema(),
'player_events',
select_expressions,
MAX_PAGE_SIZE,
request,
where=where,
args=args)
def mod(mod_uid):
"""
Gets a specific mod definition.
**Example Request**:
.. sourcecode:: http
GET /mods/DF8825E2-DDB0-11DC-90F3-3F9B55D89593
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"author": "Sorian(Current) Brent Allen(Original)",
"create_time": "2014-04-05T17:13:18+00:00",
"description": "Terrain is cratered by heavy ordinance.",
"download_url": "http://content.faforever.com/faf/vault/mods/Terrain%20Deform%20for%20FA.v0001.zip",
"downloads": 93,
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"is_ranked": false,
"is_ui": false,
"likes": 1,
"name": "Terrain Deform for FA",
"version": "1"
},
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"type": "mod"
}
}
"""
result = fetch_data(ModSchema(),
'table_mod',
SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
where="`uid` = %s",
args=mod_uid,
many=False,
enricher=enricher)
if 'id' not in result['data']:
return {'errors': [{'title': 'No mod with this uid was found'}]}, 404
return result
def mods():
"""
Lists the newest version of all non-hidden mods.
**Example Request**:
.. sourcecode:: http
GET /mods
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"author": "Sorian(Current) Brent Allen(Original)",
"create_time": "2014-04-05T17:13:18+00:00",
"description": "Terrain is cratered by heavy ordinance.",
"download_url": "http://content.faforever.com/faf/vault/mods/Terrain%20Deform%20for%20FA.v0001.zip",
"downloads": 93,
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"is_ranked": false,
"type": "UI",
"likes": 1,
"times_played": 152,
"display_name": "Terrain Deform for FA",
"version": "1"
},
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"type": "mod"
},
...
]
}
"""
return fetch_data(ModSchema(),
MODS_TABLE,
SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
enricher=enricher,
where='v.hidden = 0')
def events_list():
"""
Lists all event definitions.
**Example Request**:
.. sourcecode:: http
GET /events
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"id": "15b6c19a-6084-4e82-ada9-6c30e282191f",
"image_url": null,
"name": "Seraphim wins",
"type": "NUMERIC"
},
"id": "15b6c19a-6084-4e82-ada9-6c30e282191f",
"type": "event"
},
...
]
}
:query string language: The preferred language to use for strings returned by this method. default is en.
:query string region: The preferred region to use for strings returned by this method. default is US.
:status 200: No error
"""
language = request.args.get('language', 'en')
region = request.args.get('region', 'US')
return fetch_data(EventSchema(),
EVENTS_TABLE,
EVENTS_SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
args={
'language': language,
'region': region
})
def events_list_player(player_id):
"""
Lists the events for a player.
**Example Request**:
.. sourcecode:: http
GET /players/781/events
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"id": string,
"attributes": {
"event_id": string,
"count": integer,
"create_time": long,
"update_time": long
}
}
]
}
:status 200: No error
"""
select_expressions = copy(PLAYER_EVENTS_SELECT_EXPRESSIONS)
del select_expressions['player_id']
where = 'player_id = %s'
args = tuple([player_id])
id_filter = request.values.get('filter[event_id]')
if id_filter:
ids = id_filter.split(',')
where += ' AND event_id IN ({})'.format(','.join(['%s'] * len(ids)))
args += tuple(ids)
return fetch_data(PlayerEventSchema(), 'player_events', select_expressions,
MAX_PAGE_SIZE, request, where=where, args=args)
def achievements_list():
"""
Lists all achievement definitions.
**Example Request**:
.. sourcecode:: http
GET /achievements
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"description": "Kill your enemy in a ranked 1v1 game in under 15 minutes",
"experience_points": 10,
"id": "02081bb0-3b7a-4a36-99ef-5ae5d92d7146",
"initial_state": "REVEALED",
"name": "Rusher",
"revealed_icon_url": "http://content.faforever.com/achievements/02081bb0-3b7a-4a36-99ef-5ae5d92d7146.png",
"total_steps": null,
"type": "STANDARD",
"unlocked_icon_url": "http://content.faforever.com/achievements/02081bb0-3b7a-4a36-99ef-5ae5d92d7146.png"
},
"id": "02081bb0-3b7a-4a36-99ef-5ae5d92d7146",
"type": "achievement"
},
...
]
}
:query string language: The preferred language to use for strings returned by this method. default is en.
:query string region: The preferred region to use for strings returned by this method. default is US.
:status 200: No error
"""
language = request.args.get('language', 'en')
region = request.args.get('region', 'US')
return fetch_data(AchievementSchema(), ACHIEVEMENTS_TABLE, ACHIEVEMENT_SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request,
args={'language': language, 'region': region})
def get_map(map_id):
"""
Gets a map.
**Example Request**:
.. sourcecode:: http
GET /maps/1
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"battle_type": "FFA",
"description": "<LOC canis3v3_Description>",
"display_name": "canis3v3",
"download_url": "http://content.faforever.com/faf/vault/maps/canis3v3.v0001.zip",
"downloads": 5970,
"id": "1",
"map_type": "skirmish",
"max_players": 6,
"num_draws": 0,
"rating": 2.94119,
"folder_name": "canis3v3.v0001",
"thumbnail_url_large": "http://content.faforever.com/faf/vault/map_previews/large/canis3v3.v0001.png",
"thumbnail_url_small": "http://content.faforever.com/faf/vault/map_previews/small/canis3v3.v0001.png",
"times_played": 1955,
"version": 1,
"author": "Someone"
},
"id": "1",
"type": "map"
}
}
"""
results = fetch_data(MapSchema(), TABLE, SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request, where='version.id = %s',
args=str(map_id), many=False, enricher=enricher)
return results
def mod(mod_uid):
"""
Gets a specific mod definition.
**Example Request**:
.. sourcecode:: http
GET /mods/DF8825E2-DDB0-11DC-90F3-3F9B55D89593
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"author": "Sorian(Current) Brent Allen(Original)",
"create_time": "2014-04-05T17:13:18+00:00",
"description": "Terrain is cratered by heavy ordinance.",
"download_url": "http://content.faforever.com/faf/vault/mods/Terrain%20Deform%20for%20FA.v0001.zip",
"downloads": 93,
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"is_ranked": false,
"is_ui": false,
"likes": 1,
"name": "Terrain Deform for FA",
"version": "1"
},
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"type": "mod"
}
}
"""
result = fetch_data(ModSchema(), 'table_mod', SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request,
where="`uid` = %s", args=mod_uid, many=False, enricher=enricher)
if 'id' not in result['data']:
return {'errors': [{'title': 'No mod with this uid was found'}]}, 404
return result
def coop_leaderboards(mission, player_count):
"""
Lists a coop leaderboard for a specific mission. `id` refers to the game id.
**Example Request**:
.. sourcecode:: http
GET /coop/leaderboards
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"id": "112",
"game_id": "1337",
"ranking": 3,
"player_names": "Someone, SomeoneElse",
"secondary_objectives": true,
"duration": 3600,
},
"id": "112",
"type": "coop_leaderboard"
},
...
]
}
"""
if player_count <= 0:
table = LEADERBOARD_TABLE_ALL
else:
table = LEADERBOARD_TABLE_BY_PLAYER_COUNT
return fetch_data(CoopLeaderboardSchema(), table, LEADERBOARD_SELECT_EXPRESSIONS,
MAX_PAGE_SIZE, request, args={'player_count': player_count, 'mission': mission},
enricher=enricher)
def get_featured_mod(mod_id):
"""
Gets a featured mod.
**Example Request**:
.. sourcecode:: http
GET /featured_mods
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"id": "123",
"technical_name": "faf",
"display_name": "FA Forever",
"description": "<html>HTML Description</html>",
"visible": true,
"display_order": 1,
"git_url": "https://github.com/FAForever/fa.git",
"git_branch": "master"
},
"id": "123",
"type": "featured_mod"
}
}
"""
return fetch_data(FeaturedModSchema(),
FEATURED_MODS_TABLE,
SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
many=False,
where='id = %s',
args=mod_id)
def events_list():
"""
Lists all event definitions.
**Example Request**:
.. sourcecode:: http
GET /events
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"id": "15b6c19a-6084-4e82-ada9-6c30e282191f",
"image_url": null,
"name": "Seraphim wins",
"type": "NUMERIC"
},
"id": "15b6c19a-6084-4e82-ada9-6c30e282191f",
"type": "event"
},
...
]
}
:query string language: The preferred language to use for strings returned by this method. default is en.
:query string region: The preferred region to use for strings returned by this method. default is US.
:status 200: No error
"""
language = request.args.get('language', 'en')
region = request.args.get('region', 'US')
return fetch_data(EventSchema(), EVENTS_TABLE, EVENTS_SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request,
args={'language': language, 'region': region})
def mods():
"""
Lists all mod definitions.
**Example Request**:
.. sourcecode:: http
GET /mods
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"author": "Sorian(Current) Brent Allen(Original)",
"create_time": "2014-04-05T17:13:18+00:00",
"description": "Terrain is cratered by heavy ordinance.",
"download_url": "http://content.faforever.com/faf/vault/mods/Terrain%20Deform%20for%20FA.v0001.zip",
"downloads": 93,
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"is_ranked": false,
"is_ui": false,
"likes": 1,
"name": "Terrain Deform for FA",
"version": "1"
},
"id": "DF8825E2-DDB0-11DC-90F3-3F9B55D89593",
"type": "mod"
},
...
]
}
"""
return fetch_data(ModSchema(), 'table_mod', SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request, enricher=enricher)
def achievements_list_player(player_id):
"""
Lists the progress of achievements for a player.
**Example Request**:
.. sourcecode:: http
GET /players/781/achievements
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"items": [
{
"id": string,
"achievement_id": string,
"state": string,
"current_steps": integer,
"create_time": long,
"update_time": long
}
]
}
:param player_id: ID of the player.
:type player_id: int
:status 200: No error
"""
return fetch_data(PlayerAchievementSchema(),
'player_achievements',
PLAYER_ACHIEVEMENT_SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
where='player_id = %s',
args=player_id)
def get_player(player_id):
"""
Gets a player's public profile.
**Example Request**:
.. sourcecode:: http
GET /players/1234
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"id": "21447",
"login": "******"
},
"id": "21447",
"type": "player"
}
}
:param player_id: Player ID
:type player_id: int
:status 200: No error
"""
return fetch_data(PlayerSchema(),
PLAYER_TABLE,
PLAYER_SELECT_EXPRESSIONS,
1,
request,
many=False,
where='l.id = %s',
args=(player_id, ))
def coop_missions():
"""
Lists all coop missions.
**Example Request**:
.. sourcecode:: http
GET /coop/missions
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"category": "CUSTOM",
"description": "Prothyon - 16 is a secret UEF facillity for training new ACU pilots. Your task today is to provide a demonstration to our newest recruits by fighting against a training AI.",
"download_url": "http://content.faforever.com/faf/vault/maps/prothyon16.v0006.zip",
"id": "26",
"name": "Prothyon - 16",
"thumbnail_url_large": "http://content.faforever.com/faf/vault/map_previews/large/prothyon16.v0006.png",
"thumbnail_url_small": "http://content.faforever.com/faf/vault/map_previews/small/prothyon16.v0006.png",
"version": 6
},
"id": "26",
"type": "coop_mission"
},
...
]
}
"""
return fetch_data(CoopMissionSchema(), 'coop_map', SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request, enricher=enricher)
def achievements_list_player(player_id):
"""
Lists the progress of achievements for a player.
**Example Request**:
.. sourcecode:: http
GET /players/781/achievements
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"items": [
{
"id": string,
"achievement_id": string,
"state": string,
"current_steps": integer,
"create_time": long,
"update_time": long
}
]
}
:param player_id: ID of the player.
:type player_id: int
:status 200: No error
"""
return fetch_data(PlayerAchievementSchema(), 'player_achievements', PLAYER_ACHIEVEMENT_SELECT_EXPRESSIONS,
MAX_PAGE_SIZE, request, where='player_id = %s', args=player_id)
def clans():
return fetch_data(ClanSchema(), CLAN_LIST, SELECT_EXPRESSIONS,
MAX_PAGE_SIZE, request)
def ranked1v1():
"""
Lists all ranked 1v1 players.
**Example Request**:
**Default Values**:
page[number]=1
page[size]=5000
.. sourcecode:: http
GET /ranked1v1
Accept: application/vnd.api+json
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"deviation": 48.4808,
"id": "781",
"is_active": true,
"login": "******",
"mean": 2475.69,
"num_games": 1285,
"ranking": 1,
"rating": 2330,
"won_games": 946
},
"id": "781",
"type": "ranked1v1"
},
...
]
}
:param page[number]: The page number being requested (EX.: /ranked1v1?page[number]=2)
:type page[number]: int
:param page[size]: The total amount of players to grab by default (EX.: /ranked1v1?page[size]=10)
:type page[size]: int
:param filter[isActive]: Whether or not to filter active players or not (true or false) (EX.: /ranked1v1?filter[is_active]=true)
:type filter[isActive]: boolean
:param filter[player]: Allows search functionality in the ranked1v1 endpoint based upon the players login name (EX.: /ranked1v1?filter[player]=Zock)
:type filter[player]: name
:status 200: No error
"""
if request.values.get('sort'):
raise InvalidUsage('Sorting is not supported for ranked1v1')
page = int(request.values.get('page[number]', 1))
page_size = int(request.values.get('page[size]', MAX_PAGE_SIZE))
player = request.args.get('filter[player]')
row_num = (page - 1) * page_size
args = {'row_num': row_num}
where = ''
active_filter = request.values.get('filter[is_active]')
if active_filter:
where += 'is_active = ' + ('1' if active_filter.lower() == 'true' else '0') + ' AND r.numGames > 0'
if player:
where += " l.login LIKE %(player)s"
args['player'] = '%' + player + '%'
return fetch_data(Ranked1v1Schema(), TABLE, SELECT_EXPRESSIONS, MAX_PAGE_SIZE, request, sort='-rating',
args=args, where=where)
def list_bugreports():
"""
Lists all bug report definitions.
**Example Request**:
.. sourcecode:: http
GET /bugs
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"automatic": true,
"id": "31424",
"log": "log",
"target": {
"data": {
"attributes": {
"name": "client",
"ref": "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000",
"url": "https://github.com/FAForever/client"
},
"id": "client/tree/\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000",
"type": "bugreport_target"
}
},
"title": "Bug report",
"traceback": "traceback"
},
"id": "31424",
"type": "bugreport"
},
...
]
}
:status 200: No error
"""
def add_bugreport_target(item):
item['target'] = {
'name': item['name'],
'ref': item['ref'],
'url': item['url']
}
return fetch_data(BugReportSchema(),
TABLE,
SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
enricher=add_bugreport_target)
def leaderboards_type(leaderboard_type):
"""
Lists all ranked 1v1 or global players.
**Example Request**:
**Default Values**:
page[number]=1
page[size]=5000
.. sourcecode:: http
GET /leaderboards/1v1 /leaderboards/global
Accept: application/vnd.api+json
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"deviation": 48.4808,
"id": "781",
"login": "******",
"mean": 2475.69,
"num_games": 1285,
"ranking": 1,
"rating": 2330,
"won_games": 946
},
"id": "781",
"type": "ranked1v1"
},
...
]
}
:param page[number]: The page number being requested (EX.: /leaderboards/1v1?page[number]=2)
:type page[number]: int
:param page[size]: The total amount of players to grab by default (EX.: /leaderboards/1v1?page[size]=10)
:type page[size]: int
:param leaderboard_type: Finds players in the 1v1 or global rating
:type leaderboard_type: 1v1 OR global
:status 200: No error
"""
sort_field = request.values.get('sort')
if sort_field:
raise ApiException(
[Error(ErrorCode.QUERY_INVALID_SORT_FIELD, sort_field)])
page = int(request.values.get('page[number]', 1))
page_size = int(request.values.get('page[size]', MAX_PAGE_SIZE))
row_num = (page - 1) * page_size
select = SELECT_EXPRESSIONS
args = {'row_num': row_num}
rating = find_leaderboard_type(leaderboard_type, select)
return fetch_data(LeaderboardSchema(),
rating['table'],
rating['select'],
MAX_PAGE_SIZE,
request,
sort='-rating',
args=args,
where='is_active = 1 AND r.numGames > 0')
def leaderboards_type_get_player(leaderboard_type, player_id):
"""
Gets a global or 1v1 player. Player must be active, played more than one ranked game, and must have statistics associated
with he/she.
**Example Request**:
.. sourcecode:: http
GET /leaderboards/1v1/781 /leaderboards/global/781
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": {
"attributes": {
"deviation": 48.4808,
"id": "781",
"login": "******",
"mean": 2475.69,
"num_games": 1285,
"ranking": 1,
"rating": 2330,
"won_games": 946
},
"id": "781",
"type": "leaderboard"
}
}
:param leaderboard_type: Finds players in the 1v1 or global rating
:type leaderboard_type: 1v1 OR global
:param player_id: Player ID
:type player_id: int
:status 200: No error
:status 404: No entry with this id was found
"""
select_expressions = SELECT_EXPRESSIONS.copy()
select = select_expressions
rating = find_leaderboard_type(leaderboard_type, select)
select_expressions[
'ranking'] = """(SELECT count(*) FROM """ + rating['tableName'] + """
WHERE ROUND(mean - 3 * deviation) >= ROUND(r.mean - 3 * r.deviation)
AND is_active = 1
AND numGames > 0)
"""
result = fetch_data(LeaderboardSchema(),
rating['table'],
rating['select'],
MAX_PAGE_SIZE,
request,
many=False,
where='r.id=%(id)s',
args=dict(id=player_id, row_num=0))
if 'id' not in result['data']:
return {'errors': [{'title': 'No entry with this id was found'}]}, 404
return result
def games():
"""Searches for games.
HTTP Parameters::
Field Type Description
players string A comma delimited list of the players to search for
map_name string The map name to search for
map_exclude string If any input is provided, map provided in map_name is excluded instead of included, requires map_name
max_rating integer Inclusive maximum rating bound for all players
min_rating integer Inclusive minimum rating bound for all players
victory_condition string/integer The victory condition to search for, can be either id or name
mod string/integer The featured mod to search for, can be either id or name
rating_type string Rating type to search for, defaults to global, else `ladder` must be provided for ladder rating
max_player_count integer Inclusive maximum player count bound, uses rating_type value
min_player_count integer Inclusive minimum player count bound, uses rating_type value
max_datetime string Inclusive latest datetime (iso8601 format), based on game start time
min_datetime string Inclusive earliest datetime (iso8601 format), based on game start time
:return:
If successful, this method returns a response body with the following structure::
{
"data": [
{
"attributes": {
"game_name": string,
"host": string,
"id": string,
"map_id": integer,
"map_name": string,
"mod_id": integer,
"mod_name": string,
"players": [
{
"color": integer,
"deviation": float,
"faction": string,
"is_ai": boolean,
"login": string,
"mean": float,
"place": integer,
"player_id": string,
"score": integer,
"score_time": string,
"team": integer
}
],
"start_time": string,
"validity": string,
"victory_condition": string
}
]
"id": string,
"type": strings
}
"""
player_list = request.args.get('filter[players]')
map_name = request.args.get('filter[map_name]')
map_exclude = request.args.get('filter[map_exclude]')
max_rating = request.args.get('filter[max_rating]')
min_rating = request.args.get('filter[min_rating]')
victory_condition = request.args.get('filter[victory_condition]')
game_mod = request.args.get('filter[mod]')
rating_type = request.args.get('filter[rating_type]')
max_players = request.args.get('filter[max_player_count]')
min_players = request.args.get('filter[min_player_count]')
max_datetime = request.args.get('filter[max_datetime]')
min_datetime = request.args.get('filter[min_datetime]')
page, page_size = get_page_attributes(MAX_PLAYER_PAGE_SIZE, request)
limit_expression = get_limit(page, page_size)
errors = check_syntax_errors(map_exclude, map_name, max_datetime, min_datetime)
if errors:
return errors
if player_list or map_name or max_rating or min_rating or rating_type or victory_condition or game_mod \
or max_players or min_players or max_datetime or min_datetime:
select_expression, args, limit = build_query(victory_condition, map_name, map_exclude, max_rating, min_rating,
player_list, rating_type, max_players, min_players, max_datetime,
min_datetime, game_mod, limit_expression)
player_select_expression = PLAYER_SELECT_EXPRESSIONS
player_select_expression['max_rating'] = build_rating_selector(rating_type, MAX_RATING_HEADER_EXPRESSION)
player_select_expression['min_rating'] = build_rating_selector(rating_type, MIN_RATING_HEADER_EXPRESSION)
result = fetch_data(GameStats(), select_expression, GAME_SELECT_EXPRESSIONS,
MAX_PLAYER_PAGE_SIZE, request, args=args, sort='-id', enricher=enricher, limit=limit,
players=player_select_expression)
else:
result = fetch_data(GameStats(),
GAMES_NO_FILTER_EXPRESSION.format('gs.id', limit_expression),
GAME_SELECT_EXPRESSIONS, MAX_PLAYER_PAGE_SIZE, request, sort='-id', enricher=enricher,
limit=False, players=PLAYER_SELECT_EXPRESSIONS)
return sort_game_results(result)
def featured_mod_files(id, version):
"""
Lists the files of a specific version of the specified mod. If the version is "latest", the latest version is
returned.
**Example Request**:
.. sourcecode:: http
GET /featured_mods/123/files/3663
**Example Response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
{
"data": [
{
"attributes": {
"id": "123",
"md5": "1bdb6505a6af741509c9d3ed99670b79",
"version": "ee2df6c3cb80dc8258428e8fa092bce1",
"name": "ForgedAlliance.exe",
"group": "bin",
"url": "http://content.faforever.com/faf/updaterNew/updates_faf_files/ForgedAlliance.3659.exe"
},
"id": "123",
"type": "featured_mod_file"
},
...
]
}
"""
mods = get_featured_mods()
if id not in mods:
raise ApiException([Error(ErrorCode.UNKNOWN_FEATURED_MOD, id)])
featured_mod_name = 'faf' if mods.get(id) == 'ladder1v1' else mods.get(id)
files_table = FILES_TABLE_FORMAT.format(featured_mod_name)
where = ''
args = None
if version and version != 'latest':
where += ' AND u.version <= %s'
args = (version, )
return fetch_data(FeaturedModFileSchema(),
files_table,
FILES_SELECT_EXPRESSIONS,
MAX_PAGE_SIZE,
request,
enricher=partial(
file_enricher,
'updates_{}_files'.format(featured_mod_name)),
where_extension=where,
args=args)
