A Restful JSON API as a service for analyzing Age of Empires II records.
- Copy the
productionservice found indocker-compose.ymlto your project.
Delete test.mgz and corrupt.aoe2record from the records directory.
- Clone Deasilsoft/a2j and open the project directory with
git clone https://github.com/Deasilsoft/a2j.git && cd a2j - Make changes to docker-compose.yml as you desire.
- Run the Docker container(s) with
docker-compose up --build -d
python ./tests/data/prettier.pyto prettifymatch.jsonandsummary.json.- Run tests locally with
docker-compose exec -T development pytest --cov=src --cov-report=xml tests
- Pull the image from Docker Hub with
docker pull deasilsoft/a2j:latest - Run the Docker container with
docker run -d --name a2j -v ABSOLUTE_PATH_TO_RECORDS:/home/a2j/records --restart always deasilsoft/a2j:latest
Delete test.mgz and corrupt.aoe2record from the records directory.
Remember to replace ABSOLUTE_PATH_TO_RECORDS with your own value.
Read more about the docker run syntax.
This is a Restful API running in a Docker container preferably behind your secure firewall (security requirement). This service should not be accessible from localhost:5000
(or any other port). This is built as a service specifically to make it possible to be used with any tech stack, in particular websites not necessarily running with Python. This
service is perfect for websites built with PHP.
You can add more record files from the host by placing the record files inside the directory named records in the project directory. The purpose of the API is to easily and
efficiently retrieve the data you want from an Age of Empires II record file. The output data is JSON, which is easy to handle in any programming language. The JSON data is cached
to increase speed and reduce usage of your valuable computing power.
Path and query parameters within <> or [] brackets are dynamic values. <> are required, and [] are optional. Optional values have default values, which are given after
the | separator. Example [optional=foo,bar|bar] allows foo and bar as valid values, but bar is the default value if no value is supplied.
container_name:5000/
container_name:5000/minimap/<record>/?[scale=1-15|5]
container_name:5000/record/<record>/<commands...>/?[method=summary,match|summary]
Whenever you get a list of endpoints from a request, you can add one of them at the end of your current path (before query parameters).
Below are some examples of usage. These examples use curl as a tool to send requests, any other means of sending requests will work as well. container_name is an example name
of the Docker container running Deasilsoft/a2j. We strongly recommend naming the container a2j and NOT publishing the port.
This example will retrieve a JSON object of all the teams and players from the test.mgz record.
curl container_name:5000/record/test.mgz/teams/players/
This example will retrieve a JSON object of all the actions from the test.mgz record.
curl container_name:5000/record/test.mgz/actions/?method=match
This example will retrieve a PNG image with our interpretation of the Age of Empires II minimap.
curl container_name:5000/minimap/test.mgz/
To delete all cached data from a record file you can do the following.
curl -X DELETE container_name:5000/record/test.mgz/
This is useful in cases where you replace a record file and want to generate a new cache for it. Generally, you don't want to remove cached data unless the record file has been replaced with a new record file.
| Task | Priority |
|---|---|
| Create Record as an object. | Low |
| Create Minimap with the Builder pattern. | Low |
| Create RecordParser with the Builder pattern. | Low |
- Thanks to @happyleavesaoc for maintaining aoc-mgz and for answering my questions on Discord.
- Thanks to recanalyst for minimap colors.