{"id":14065426,"url":"https://github.com/ajoyoommen/flask-rest-api-template","last_synced_at":"2025-07-29T20:32:43.459Z","repository":{"id":47203925,"uuid":"150889936","full_name":"ajoyoommen/flask-rest-api-template","owner":"ajoyoommen","description":"This repository can be used to setup a REST API in flask with Swagger documentation. The folders are structured to allow versioned API. This project is also enabled with a Dockerfile and sample unit test layout.","archived":false,"fork":false,"pushed_at":"2021-09-08T15:43:31.000Z","size":474,"stargazers_count":13,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-13T07:08:46.852Z","etag":null,"topics":["coverage","docker","flake8","flask","flask-restplus","flask-restx","pytest","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ajoyoommen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-29T18:00:04.000Z","updated_at":"2024-02-13T11:10:48.000Z","dependencies_parsed_at":"2022-09-22T21:50:38.735Z","dependency_job_id":null,"html_url":"https://github.com/ajoyoommen/flask-rest-api-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoyoommen%2Fflask-rest-api-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoyoommen%2Fflask-rest-api-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoyoommen%2Fflask-rest-api-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajoyoommen%2Fflask-rest-api-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajoyoommen","download_url":"https://codeload.github.com/ajoyoommen/flask-rest-api-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228046152,"owners_count":17861101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coverage","docker","flake8","flask","flask-restplus","flask-restx","pytest","swagger-ui"],"created_at":"2024-08-13T07:04:29.177Z","updated_at":"2024-12-04T04:31:08.181Z","avatar_url":"https://github.com/ajoyoommen.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Production-ready REST API in Flask\n\n## Usage\n\n### Install and run locally\n\n* Create python3 virtual environment and activate it\n\n      python3 -m venv venv\n      source venv/bin/activate\n\n* Install requirements\n\n      pip install -r sample_project/requirements.txt\n\n* Run development server\n\n      python run.py\n\n  You will find the development server starting like this:\n\n         * Serving Flask app \"sample_project.app\" (lazy loading)\n         * Environment: production\n           WARNING: Do not use the development server in a production environment.\n           Use a production WSGI server instead.\n         * Debug mode: on\n         * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)\n         * Restarting with stat\n         * Debugger is active!\n         * Debugger PIN: ...\n\n* View the Swagger API docs in your browser:\n\n   http://localhost:5000/sample_project/api/v1.0/doc/\n\n* Static code analysis - run this command:\n\n      flake8\n\n* Run unit tests\n\n      pytest .\n\n* Generate test case coverage\n\n      coverage run -m pytest \u0026\u0026 coverage report --omit='*lib/*.py,*test_*.py'\n      coverage xml -i\n\n\n## Running on docker\n\n* Build image and run\n\n      docker build -t project:1 .\n      docker run --name project --env-file .env -d -p 8000:8000 project:1\n\n* View Swagger API docs in the browser\n\n  http://localhost:8000/sample_project/api/v1.0/doc/\n\n* Run tests in the docker container\n\n      docker exec -it project bash\n      pytest .\n\n\n## Features\n\n### 1. Modular application ([application factory](https://flask.palletsprojects.com/en/master/patterns/appfactories/) \u0026 [blueprint](https://flask.palletsprojects.com/en/master/blueprints/))\n\nHas a `create_app` function that can be passed the environment (dev, test, prod). Environments can be be defined in the `config.py` .\n\nAPIs for a particular version are packed into a blueprint. There is also a blueprint for a healthcheck URL.\nThese blueprints are registered in `create_app` and the URL prefixes can be customised there:\n\n        app.register_blueprint(api, url_prefix=ROOT_URL + '/api/v1.0')\n        app.register_blueprint(healthcheck, url_prefix=ROOT_URL + '/version')\n\n### 2. REST APIs (Flask-restx, previously flask-resplus)\n\n\u003e Flask-RESTX is an extension for Flask ... Flask-RESTX encourages best practices with minimal setup... collection of\n\u003e decorators and tools to describe your API and expose its documentation properly (using Swagger).\n\nThe Swagger docs can be hosted at required path using `API_DOCS_URL` or can be disabled by setting its value to `False`.\nCheck out `config.py` for more examples.\n\n### 3. Unit testing (flask-testing)\n\nDefines `AppTestCase` in `sample_project.tests.conftest.py`. Tests can be found at `person.v1.test_views.py` and `user.v1.test_views.py`\n\n**Structure**\n\n### 4. WSGI app for hosting on production\n\nCan be run using `gunicorn` like this:\n\n    gunicorn -c gunicorn_config.py wsgi:app\n\nIf your application is hosted behind a reverse proxy like NGINX, the `X-Forwareded-*` headers can be corrected using\nwerkzeug's [ProxyFix](https://werkzeug.palletsprojects.com/en/1.0.x/middleware/proxy_fix/). This has already been done\nin `wsgi.py`\n\n### 5. Structure of the project\n\n```\nsample_project/\n├── api_v1.py                     # Api() object associated to Blueprint() object, person and user namespaces are added to this\n├── app.py                        # Flask() object, with blueprints registered\n├── config.py\n├── healthcheck.py\n├── __init__.py\n├── person\n│         ├── __init__.py\n│         └── v1                  # Namespace() object for person\n│             ├── __init__.py\n│             ├── test_views.py\n│             └── views.py        # Resource() objects associated to person namespace\n├── requirements.txt\n├── tests\n│         ├── conftest.py\n│         └── __init__.py\n└── user\n    ├── __init__.py\n    └── v1                       # Namespace() object for user\n        ├── __init__.py\n        ├── test_views.py\n        └── views.py             # Resource() objects associated to user namespace\n```\n\nThis layout explains an optimal way to use flask-restx with blueprints.\n\n* Many `Resource`s are linked to a `Namespace`. A namespace pertains to URLs for a particular\nmodel (say, person) and API version (say v1.0).\n* For an API version, say v1.0 an `Api` instance is created and attached to a `Blueprint` for that versoin.\n* All `Namespace`s for a specific API version are added to the previously created `Api`.\n* All the `Blueprint`s are registered with the `Flask()` object in `app.py`.\n`sample_project.api_v1`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajoyoommen%2Fflask-rest-api-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajoyoommen%2Fflask-rest-api-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajoyoommen%2Fflask-rest-api-template/lists"}