[TOC]

The API enables logged in users to more easily query ladder data.

Currently the API exposes data as it is structured within the database.

The API uses the Django Rest Framework: <https://www.django-rest-framework.org/>

## Usage

You need to be logged in to view the API via the website. If you are, endpoints are listed here: <https://aiarena.net/api/>  
To get an API token go [here](https://aiarena.net/profile/token/).

### List data objects - 
https://aiarena.net/api/ENDPOINT/  
Get a list of matches: <https://aiarena.net/api/matches/>

### Get specific item
https://aiarena.net/api/ENDPOINT/ITEM_ID  
Get match ID 4567: <https://aiarena.net/api/matches/4567>

### Filter
https://aiarena.net/api/ENDPOINT/?FIELD_NAME=VALUE  
Get all active users: <https://aiarena.net/api/users/?is_active=true>

### Search
https://aiarena.net/api/ENDPOINT?search=SEARCH_STRING  
Search for users with "lad" in one of their fields: <https://aiarena.net/api/users?search=lad>

### Order
https://aiarena.net/api/ENDPOINT?ordering=FIELD  
Get most recent results first: <https://aiarena.net/api/results?ordering=-created>

## Example scenarios:

### Download all of a bot's replays:

1. Obtain the bot's id from <https://aiarena.net/api/bots/>  
2. Get a list of all the bot's participations in matches: https://aiarena.net/api/match-participations/?bot=BOT_ID_HERE  
3. For each match id in the participants list:  
&nbsp;&nbsp;&nbsp;&nbsp;Get the result for that match: https://aiarena.net/api/results/?match=MATCH_ID_HERE  
&nbsp;&nbsp;&nbsp;&nbsp;Download the replay using the URL in the replay_file field

### Use Python to download the bot's latest 100 replays
1. Obtain your API Token [here](https://aiarena.net/profile/token/)
2. Follow the above steps to get the bot's id
3. Execute the following (after inputting necessary values):
```python
import json
import os

import requests

# Download
bot_id = 0  # insert bot id
token = ''  # insert token you received from admin
file_path = './replays/'  # insert file path
auth = {'Authorization': f'Token {token}'}

# requests.get(url).text returns a dictionary formatted as a string and we need dictionaries
response = requests.get(f'https://aiarena.net/api/match-participations/?bot={bot_id}', headers=auth)
assert response.status_code == 200, 'Unexpected status_code returned from match-participations'
participation = json.loads(response.text)
for i in range(len(participation['results'])):
    print(f'Downloading match {participation["results"][i]["match"]}')
    response = requests.get(f'https://aiarena.net/api/results/?match={participation["results"][i]["match"]}', headers=auth)
    assert response.status_code == 200, 'Unexpected status_code returned from results'
    match_details = json.loads(response.text)
    replay_file = match_details['results'][0]['replay_file']
    if replay_file not in (None, 'null'):
        replay = requests.get(replay_file, headers=auth)
        with open(os.path.join(file_path, str(participation["results"][i]["match"])+'.SC2Replay'), 'wb') as f:
            f.write(replay.content)
```

### Get the top 10 active bots ranked by ELO
Order by `elo` descending, and limit the page to 10 entries:  
<https://aiarena.net/api/bots/?active=true&ordering=-elo&limit=10>


### Update your bot
Below is an example python script for updating your bot.  
This includes the ability to update your bot's zip file and data file. 

```
import requests

my_bot_id = 1                             # You can obtain this from the URL of your bot's page: https://aiarena.net/bots/<bot_id>/
token = "<token here>"                    # insert the token you received from your token page: https://aiarena.net/profile/token/
my_bot_zip_file = "./bot_zip.zip"         # the file path to your bot zip
my_bot_data_zip_file = "./bot_data.zip"   # the file path to your bot's new data zip
my_bot_article_content = """  
    # My bot
    This is my bot. It is very good.
"""                                       # this content appears on your bot's page, under the "Biography" header
my_bot_zip_publicly_downloadable = True   # setting this to False will stop other users downloading your bot zip
my_bot_data_publicly_downloadable = True  # setting this to False will stop other users downloading your bot data


auth = {"Authorization": f"Token {token}"}
with (open(my_bot_zip_file, "rb") as bot_zip, 
      open(my_bot_data_zip_file, "rb") as bot_data):
    response = requests.patch(
        f"https://aiarena.net/api/bots/{my_bot_id}/",
        headers=auth,
        data={
            "bot_zip_publicly_downloadable": my_bot_zip_publicly_downloadable,
            "bot_data_publicly_downloadable": my_bot_data_publicly_downloadable,
            "wiki_article_content": my_bot_article_content
        },
        files={
            "bot_zip": bot_zip,
            "bot_data": bot_data,
        },
    )
    print(response.json())
```