This repository holds the web api (written in python) that is run on the server to provide required REST services to clients. It is adapted to JSON API.
Currently documentation is sparse. Please help us out!
When downloading from git be sure to run git clone --recurse-submodules on initial install, or if it is already cloned then run git submodule update --init.
Get docker.
Quick overview of Docker can be found: Docker Quick Start Guide
First you must install and configure the database component faf-db You can either manually install the component and follow the instructions on the Github page or run init_and_wait_for_db.sh (Linux and OS X only).
Now you can run the script by typing (You will need netcat installed on the computer)
./init_and_wait_for_db.sh
You will need to modify config.example.py with the correct database parameters OR update environment variables.
Build the container using
docker build -t faf-api .
Run using
docker run -d --name faf-api --link faf-db:db -p 8080:8080 faf-api
Check to see if running by looking at the container and netstat
docker ps
If using linux, you can now access the api at http://localhost:8080, otherwise follow below instructions.
Find containers IP (Container ID can be found under docker ps)
docker inspect <container_id> (IP is under IPAddress in NetworkSettings)
With the containers IP you can access the API by going to http://IP:8080/ranked1v1
If you would like to access the IP through an easy URL, then modify yours hosts file /etc/hosts
IP dev.faforever.com
You can then access the API by going to http://dev.faforever.com:8080
Logs are viewable by
docker logs faf-api
If you want to view the raw JSON on the website, then you will need to allow 'Allow-Control-Allow-Origin'' in the browser. Here is an example extension for Chrome - (https://chrome.google.com/webstore/detail/allow-control-allow-origi/nlfbmbojpeacfghkpbjhddihlkkiljbi?hl=en)
Documentation is currently handled by Sphinx until there is a more solid API. The documentation can be built using the following command:
./create_documentation.sh
This API should follow JSON API (sorting, paging, limiting, selecting fields). For this reason we recommend to use fetch_data#query_commons.py.
Take a look at the other API endpoints. For serialization & deserialization a marshmallow-jsonapi Schema is needed.
FAForever schemas are located in faftools. Push a new schema to a GitHub branch and execute this command to test it:
sudo pip3 install --upgrade git+<YourGitRepo>@<YourBranch>#egg=faftools
e.g.
sudo pip3 install --upgrade git+https://github.com/FAForever/faftools.git@feat/clan#egg=faftools
This API implements OAuth 2.0, you find a basic OAuth tutorial here. Here a FAF tutorial:
http://tools.ietf.org/html/rfc6749#section-4.1.1
- Add your OAuth client into the table
oauth_clients - Request it
/oauth/authorize?client_id=<YourClientId>&response_type=code
https://tools.ietf.org/html/rfc6749#section-4.2.1
- Add your OAuth client into the table
oauth_clients - Request it
/oauth/authorize?client_id=<YourClientId>&response_type=token