-
Notifications
You must be signed in to change notification settings - Fork 128
The ADS‐B Portal API
The ADS-B Portal API is currently in development.
The ADS-B Portal API is the backend of the future version of the ADS-B Portal being developed using the Angular framework. It is meant to share data between an ADS-B Receiver installation and the ADS-B Portal frontend. It should be noted that the ADS-B Receiver API is not being developed specifically for the ADS-B Portal frontend. The API is being built to OpenAPI v3.1.0 specifications allowing developers to generate an SDK specific to many popular programming languages for use with their own custom or community driven frontend.
At this time the API currently exposes data currently available in the soon to be legacy PHP based ADS-B Receiver portal. As development progresses more data points will be made available via the API.
The ADS-B Portal API will be released ahead of the ADS-B Portal frontend. The current ROADMAP makes the API available in the upcoming v2.9 release before the v3.0 release which will make the ADS-B Portal frontend available to the public.
Until it is officially released, development of the API can be tracked in the portal branch located in this repository. It should be noted that at this time there is no automated installation script available for the API. In order to test the API, you will either need to set it up manually or run it in your favorite IDE.
The API can be developed and debugged in your favorite IDE as long as it supports Python development. The following are instruction on how to set up the project in Visual Studio Code. Information on setting up a development environment on additional IDEs will be made available over time.
Clone the repository and checkout the portal branch.
git clone https://github.com/jprochazka/adsb-receiver`
git checkout portal
Visual Studio Code can be downloaded free from here.
Make sure you have Python installed along with the Visual Studio Code Python Extension before continuing. To check if Python is installed run one of the following commands depending on the operating system you are doing your development or testing on.
Linux/MacOS
python3 --version
Windows
python --version
Open Visual Studio Code and open the folder containing the backend code.
~/adsb-receiver/build/portal/backend
You will need to create a virtual environment in which the code will run. To do so open the Command Palette (Ctrl+Shift+P) and start typing "Python: Create Environment" to search for the proper command. After locating the command click on it. You will then be asked to select an environment. Now select Venv from the list. After doing so you will be presented with a list of interpreters installed on your computer. Select Python 3.12.x from this list.
The following packages need to be installed in order to fulfill dependencies. Run the following command in the terminal within Visual Studio Code in order to download and install these requirements.
python -m pip install coverage flask Flask-APScheduler flask-jwt-extended marshmallow mysqlclient psycopg2 pytest pyyaml
As development progresses the list of packages the project is dependent upon will grow so check back often!
A requirement.txt file is now available to help automate the installation of pip packages needed to run the API.
You may need to exit then restart Visual Studio Code in order to properly install these packages into the environment you created.
In order to debug the application, you will need to open the Run and Debug (Ctrl+Shift+D) view. Once open you should see a link stating "create a launch.json file" which you will need to click. Select "Flask" from the Command Palette when presented. A new launch.json file will be created which tells Visual Studio code how to run and debug the application.
To start debugging the application press F5.
To stop debugging press Ctrl+C in the terminal.
Once the application is running a Swagger UI page is available offering documentation and a way to test the API.
http://127.0.0.1:5000/api/docs
Contained within the tests directory is a series of Python files making use of pytest and coverage. In order to help ensure the ADS-B Portal API remains in working order, contributions to the project will require that these tests result in passing grades. This will be enforced via the utilization of GitHub Actions once v2.9 is released. New tests should be submitted for additional functionality when submitted.
Test can be run via a number of commands.
pytest or coverage run -m pytest
If using coverage, a report on test coverage can be viewed by running the command coverage report.
To generate an HTML representation of the coverage report run coverage html to generate a folder named htmlcov containing a detailed HTML representation of the coverage report.
If you wish to contribute and are new to testing don't be afraid to ask for help!
A rudimentary form of authentication has been added to the API. Authentication is accomplished through the use of JWT refresh and access tokens. In order to access protected endpoints, you will first need to generate a refresh token using http://127.0.0.1:5000/api/token/login. This will generate both a refresh token as well as an access token. Passing the access token in the request header as Authorization: Bearer <access_token> when making a call to a protected endpoint will allow the request to be fulfilled. When requesting a new access token using http://127.0.0.1:5000/api/token/refresh you will need to pass the refresh token instead, Authorization: Bearer <refresh_token>. Doing so will result in a freshly minted access token being returned.
It is important to keep in mind that at this time refresh tokens can be generated without authenticating via username and password.
The Python scripts responsible for gathering flight data from dump1090 and the database maintenance script are now part of the ADS-B Portal API project. These tasks are now scheduled and run by Flask-APScheduler instead of by crontab as they were in the past. These as well as any additional scripts which may be added in the future can be located in the ~/backend/jobs directory.
The scheduler can be controlled via the API using endpoints located within http://127.0.0.1:5000/api/scheduler.
Authentication has not been set up yet so access to many of the scheduler endpoints is currently denied.
The scheduler endpoints are not documents in the OpenAPI specification as of this time.