Blindo GraphQL API

Status

This repository is published as historical open source code. The project has been unmaintained since September 2022, no active development or support is provided, and there are no guarantees of any kind. It is released under the GNU Affero General Public License v3.0 (or any later version) so that its code remains useful to the community for educational, accessibility, and research purposes.

Contributions are not actively reviewed. Forks and derivative works are welcome under the terms of the AGPL-3.0-or-later license (see LICENSE and COPYRIGHT).

What's Blindo?

Blindo is the first and the biggest labels repository for Talkback users in the world, we work as a social app where anybody can collaborate uploading new Talkback labels and all these labels can be downloaded with just one click, also the collaborators can rate the usability and accessibility of your favorite Android apps to share with the world the best accessible apps to allow the blind community to use Android easier.

Installation

Prepare your local environment

Cloning repository

First clone this repository to your local environment, also you can create a new fork and work with it:

  $ git clone https://github.com/parisbs/blindo-api.git

Set the .env file

When you have the code in your local environment copy and rename the .env.example to .env and edit the values of all environment variables, here are a little description about each one: Note: Just modify the values listed below

• ENV (String): environment to run, you can set dev|prod|test
• DB_HOST (String): address to your DB server
• DB_USER (String): user to login in DB
• DB_PASSWORD (String): password for the DB user
• DB_DATABASE (String): name of the database for the project in DB
• DB_DIALECT (String): the DB engine dialect to use, e.g. postgresql or mysql
• DB_DRIVER (String): the DB driver to use
• DB_ENCODING (String): encoding to use in DB connections and tables, recommended utf8 for PostgreSQL and utf8mb4 for MySQL
• DB_COMMIT_ON_TEARDOWN (Boolean): if the DB should commit on teardown
• DB_TRACK_MODIFICATIONS (Boolean): if the DB should track modifications
• API_PORT (Integer): the port to use with Gunicorn
• AUTHENTICATION_SERVICE (String): the service to authenticate JWT headers, possible values are google, firebase, test (Note: test skips JWTs and returns the USER_SUB_FOR_DEBUG as user sub)
• AUTHORIZED_ISSES ([String]): the authorized isses to authenticate separated by commas (,)
• AUTHORIZED_AUDIENCE ([String]): the authorized audiences to authenticate separated by commas (,)
• USER_SUB_FOR_DEBUG (String): the SUB value to use for debug purposes when authentication is required
• GOOGLE_APPLICATION_CREDENTIALS (String): the path to your Google credentials JSON file
• AZ_VISION_PROJECT (String): the Azure Computer Vision project name to generate the Azure endpoint
• AZ_VISION_KEY (String): the API key for Azure Computer Vision service

Install Virtualenv or Pyenv

Now you need Virtualenv or Pyenv to install and prepare your environment, show how to install it in your OS in the following links:

• Virtualenv for Windows, Linux and Mac you can use PIP, see how
• Pyenv for Windows, Linux and Mac you can see the installation manual here

When you already have any wrapper installed create a new environment using python 3.10.4 and activate it, if is necessary create your .python-version file:

$ # If you use Pyenv
  $ echo "your_environment_name" > .python-version
  $ pyenv activate
  $ # If you use Virtualenv
  $ source [your_environment_name]/bin/activate

Install dependencies and database

Install all the project dependencies, create new user and database in DB and run the tests to verify taht's all right

  $ make install-deps
  $ DB.server start
  $ # Use your DB credentials and remove the -p if you do not set your DB password yet
  $ DB -u root -p
  $ DB> create database blindo_api;
  $ DB> create database blindo_api_test;
  $ DB> create user '[user_name]'@'%' identified by '[your_password]';
  $ DB> grant all privileges on blindo_api.* to '[user_name]'@'%';
  $ DB> grant all privileges on blindo_api_test.* to '[user_name]'@'%';
  $ DB> exit
  $ make db-upgrade
  $ make unit-tests

All the tests should be passed, if not please verify if you have your python environment activated or all the dependencies were installed correctly, then try again

Run the project

You can see the project working with the following command:

  $ make run

Then go to localhost:[port]/graphql

About the project directories

In the root path of the project you can find some configuration and extra files

• .coveragerc: configuration for Coverage
• .editorconfig: configuration for the code style
• .env.example: example for environment variables file, recommend to copy and rename the copy to avoid missing variables
• .gitignore: list of git ignored files and directories
• .htaccess.example: example of htaccess file for Passenger configuration for hosting services
• config.py: configuration file to support multiple environments
• LICENSE: full text of the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) under which this project is distributed
• COPYRIGHT: short copyright notice and license summary
• Makefile: make commands file
• myapp.py: create Flask instance to use it with Passenger servers
• passenger_wsgi.py: Passenger script to run the API
• PULL_REQUEST_TEMPLATE.md: template for pull requests in GitHub
• README.md: this readme file
• requirements.txt: list of dependencies for the project
• tox.ini: configuration for Tox module for testing, linters and coverage

blindo directory

In this directory you can find the main api module and the init file:

• api.pi: create the api instance to run with gunicorn
• init.py: initialize and configure the Flask instance with all the namespaces

controllers directory

Here you can set your namespaces directories and register them in init file:

• init.py: import and register all the available namespaces to use in your flask API
• [namespaces directories]

namespaces directories

In these paths you can put your python code for each endpoint and method:

• __init.py: create the namespace for your endpoint
• views.py: create the endpoint class and the methods behavior

models directory

Here you can add all your data models for SQLAlchemy, recommend to inheritance from base class

• init.py: import all the models
• [model_files].py: define your SQLAlchemy models

schemas directory

Storage all the schemas for your SQLAlchemy models to serialize them in responses

• init.py: required to register new python module
• [shema_files].py: define your schemas using flask_restplus.fields

Utils directory

Here you can add any extra util for the API

• init.py: required to register new python module
• [util_files].py: optional if you want to create your utils in this directory directly
• [utils_directories]/: separate your utils by directories

decorators directory

In this path you can add your decorators

• authentication.py: the require_auth decorator to allows JWT authorization in your endpoints

migrations directory

Here you can configure your migration scripts template and your migration scripts for Flask-Migrate

• alembic.ini: the migration configuration
• env.py: script to auto generate your database migrations
• script.py.mako: template for your migration scripts

versions directory

Storage all your migration scripts for your database

• [%year%-%month%-%day%_%slug%].py: migration script file with your DB sentences and definitions

tests directory

All the tests for the project

• init.py: required to register new python module

functional directory

For all your functional tests

• init.py: require to register new python module
• [test_files.py|tests_directories|utils_directories_or_files.py]: for your functional tests

unit directory

Storage your unit tests for the project

• init.py: required to register new python module
• conftest.py: configuration, fixtures and mocks for your tests
• [test_files].py: unit tests for your endpoints or utils

factories directory

Here you can create your SQLAlchemy factories to poblate your tables and prepare fake data in your database

• init.py: required to register new python module
• [factory_files].py: your factory definitions

.github directory

Here you can add templates for GitHub issues and more

ISSUE_TEMPLATE directory

Storage the issues template to use in GitHub

• bug_report.md: template for report issues

git-hooks directory

In this path you can add your custom git hooks

• pre-commit: git hook to run tests before commit changes

How to create new migration script

The project uses Flask-Migrate to generate database migration scripts to make easier the database management, follow these steps to create a new one:

1. Be sure that your new models are ready and have all the parameters and configurations to production, also verify that your DB server is running
2. Run the command make db-migrate message='short migration description', the message parameter is required
3. Go to the new migration file generated in migrations/versions/ path and verify that's all right, modify the code if is necessary
4. Run the command make db-upgrade to apply the changes to the database
5. Also you can undo migrations using the command make db-downgrade with the optional parameter revision where you must pass the revision ID of the target migration file to downgrade

Passenger servers

This project supports Passenger servers, verify if your hosting provider support python apps and Passenger controller before use this feature

You can configure your Passenger instance using the .htaccess file, copy and rename the .htaccess.example file to know what variables you must set to work, some providers can generate automaticaly the .htaccess file, verify if your provider support this feature or go to your cPanel and verify if you have a section called Python apps

Warning

Please change credentials in local, test or development environments to prevent security issues

License

Blindo API is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

The full license text is included in the LICENSE file. A short copyright notice is available in COPYRIGHT. If you did not receive a copy of the license along with this program, see https://www.gnu.org/licenses/agpl-3.0.html.

Because Blindo API is intended to be deployed as a network service, the AGPL-3.0 ensures that any modified version made available to users over a network must also make its complete corresponding source code available to those users. This is a deliberate choice to keep improvements in the open and prevent proprietary forks of a project that was created to benefit the blind and visually impaired community.

Colaboration

You can colaborate to make this project better, just following these recommendations:

• Do not deactivate linters and other unit tests to commit your changes
• Use the pull request template to provide information about your changes
• Be clear in your pr explaination
• Create the functional or unit tests for your features
• Comment the functions and classes if is necessary, specialy in complex code
• To create a new pull request first fork the project and make your changes in the fork
• Follow the GitFlow pattern for your branches and make your pr to develop branch