{"id":13501627,"url":"https://github.com/antkahn/flask-api-starter-kit","last_synced_at":"2025-03-29T09:31:00.101Z","repository":{"id":50303175,"uuid":"74295887","full_name":"antkahn/flask-api-starter-kit","owner":"antkahn","description":"Start a Flask API in less than 5 minutes","archived":false,"fork":false,"pushed_at":"2023-02-02T06:24:19.000Z","size":65,"stargazers_count":450,"open_issues_count":10,"forks_count":121,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-31T20:40:40.413Z","etag":null,"topics":["api","black","boilerplate","docker","flake8","flask","flask-api","isort","lint","python","starter-kit","swagger"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antkahn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-20T19:01:35.000Z","updated_at":"2024-10-16T11:18:10.000Z","dependencies_parsed_at":"2023-02-17T15:15:55.759Z","dependency_job_id":null,"html_url":"https://github.com/antkahn/flask-api-starter-kit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antkahn%2Fflask-api-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antkahn%2Fflask-api-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antkahn%2Fflask-api-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antkahn%2Fflask-api-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antkahn","download_url":"https://codeload.github.com/antkahn/flask-api-starter-kit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246167063,"owners_count":20734378,"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":["api","black","boilerplate","docker","flake8","flask","flask-api","isort","lint","python","starter-kit","swagger"],"created_at":"2024-07-31T22:01:44.154Z","updated_at":"2025-03-29T09:30:59.822Z","avatar_url":"https://github.com/antkahn.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Flask Api Starter Kit [![CircleCI](https://circleci.com/gh/antkahn/flask-api-starter-kit/tree/master.svg?style=svg)](https://circleci.com/gh/antkahn/flask-api-starter-kit/tree/master) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/antkahn/flask-api-starter-kit/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/antkahn/flask-api-starter-kit/?branch=master)\n\nThis starter kit is designed to allow you to create very fast your Flask API.\n\nThe primary goal of this project is to remain as **unopinionated** as possible. Its purpose is not to dictate your project structure or to demonstrate a complete sample application, but to provide a set of tools intended to make back-end development robust, easy, and, most importantly, fun.\n\nThis starter kit comes with a [tutorial](https://github.com/antkahn/flask-api-starter-kit/blob/tutorial/doc/installation.md).\nCheck it out if you want a quick tutorial on how to use Flask with this architecure.\n\n## Table of Contents\n\n1. [Dependencies](#dependencies)\n1. [Getting Started](#getting-started)\n1. [Commands](#commands)\n1. [Database](#database)\n1. [Application Structure](#application-structure)\n1. [Development](#development)\n1. [Testing](#testing)\n1. [Lint](#lint)\n1. [Format](#format)\n1. [Swagger](#swagger)\n\n## Dependencies\n\nYou will need [docker](https://docs.docker.com/engine/installation/) and [docker-compose](https://docs.docker.com/compose/install/).\n\n## Getting Started\n\nFirst, clone the project:\n\n```bash\n$ git clone https://github.com/antkahn/flask-api-starter-kit.git \u003cmy-project-name\u003e\n$ cd \u003cmy-project-name\u003e\n```\n\nThen install dependencies and check that it works\n\n```bash\n$ make server.install      # Install the pip dependencies on the docker container\n$ make server.start        # Run the container containing your local python server\n```\n\nIf everything works, you should see the available routes [here](http://127.0.0.1:3000/application/spec).\n\nThe API runs locally on docker containers. You can easily change the python version you are willing to use [here](https://github.com/antkahn/flask-api-starter-kit/blob/master/docker-compose.yml#L4), by fetching a docker image of the python version you want.\n\n## Commands\n\nYou can display availables make commands using `make`.\n\nWhile developing, you will probably rely mostly on `make server.start`; however, there are additional scripts at your disposal:\n\n| `make \u003cscript\u003e`      | Description                                                                  |\n| -------------------- | ---------------------------------------------------------------------------- |\n| `help`               | Display availables make commands                                             |\n| `server.install`     | Install the pip dependencies on the server's container.                      |\n| `server.start`       | Run your local server in its own docker container.                           |\n| `server.daemon`      | Run your local server in its own docker container as a daemon.               |\n| `server.upgrade`     | Upgrade pip packages interactively.                                          |\n| `database.connect`   | Connect to your docker database.                                             |\n| `database.migrate`   | Generate a database migration file using alembic, based on your model files. |\n| `database.upgrade`   | Run the migrations until your database is up to date.                        |\n| `database.downgrade` | Downgrade your database by one migration.                                    |\n| `test`               | Run unit tests with pytest in its own container.                             |\n| `test.coverage`      | Run test coverage using pytest-cov.                                          |\n| `test.lint`          | Run flake8 on the `src` and `test` directories.                              |\n| `test.safety`        | Run safety to check if your vendors have security issues.                    |\n| `format.black`       | Format python files using Black.                                             |\n| `format.isort`       | Order python imports using isort.                                            |\n\n## Database\n\nThe database is in [PostgreSql](https://www.postgresql.org/).\n\nLocally, you can connect to your database using :\n\n```bash\n$ make database.connect\n```\n\nHowever, you will need before using this command to change the docker database container's name [here](https://github.com/antkahn/flask-api-starter-kit/blob/master/package.json#L6).\n\nThis kit contains a built in database versioning using [alembic](https://pypi.python.org/pypi/alembic).\nOnce you've changed your models, which should reflect your database's state, you can generate the migration, then upgrade or downgrade your database as you want. See [Commands](#commands) for more information.\n\nThe migration will be generated by the container, it may possible that you can only edit it via `sudo` or by running `chown` on the generated file.\n\n## Application Structure\n\nThe application structure presented in this boilerplate is grouped primarily by file type. Please note, however, that this structure is only meant to serve as a guide, it is by no means prescriptive.\n\n```\n.\n├── devops                   # Project devops configuration settings\n│   └── deploy               # Environment-specific configuration files for shipit\n├── migrations               # Database's migrations settings\n│   └── versions             # Database's migrations versions generated by alembic\n├── src                      # Application source code\n│   ├── models               # Python classes modeling the database\n│   │   ├── abc.py           # Abstract base class model\n│   │   └── user.py          # Definition of the user model\n│   ├── repositories         # Python classes allowing you to interact with your models\n│   │   └── user.py          # Methods to easily handle user models\n│   ├── resources            # Python classes containing the HTTP verbs of your routes\n│   │   └── user.py          # Rest verbs related to the user routes\n│   ├── routes               # Routes definitions and links to their associated resources\n│   │   ├── __init__.py      # Contains every blueprint of your API\n│   │   └── user.py          # The blueprint related to the user\n│   ├── swagger              # Resources documentation\n│   │   └── user             # Documentation of the user resource\n│   │       └── GET.yml      # Documentation of the GET method on the user resource\n│   ├── util                 # Some helpfull, non-business Python functions for your project\n│   │   └── parse_params.py  # Wrapper for the resources to easily handle parameters\n│   ├── config.py            # Project configuration settings\n│   ├── manage.py            # Project commands\n│   └── server.py            # Server configuration\n└── test                     # Unit tests source code\n```\n\n## Development\n\nTo develop locally, here are your two options:\n\n```bash\n$ make server.start           # Create the containers containing your python server in your terminal\n$ make server.daemon          # Create the containers containing your python server as a daemon\n```\n\nThe containers will reload by themselves as your source code is changed.\nYou can check the logs in the `./server.log` file.\n\n## Testing\n\nTo add a unit test, simply create a `test_*.py` file anywhere in `./test/`, prefix your test classes with `Test` and your testing methods with `test_`. Unittest will run them automaticaly.\nYou can add objects in your database that will only be used in your tests, see example.\nYou can run your tests in their own container with the command:\n\n```bash\n$ make test\n```\n\n## Lint\n\nTo lint your code using flake8, just run in your terminal:\n\n```bash\n$ make test.lint\n```\n\nIt will run the flake8 commands on your project in your server container, and display any lint error you may have in your code.\n\n## Format\n\nThe code is formatted using [Black](https://github.com/python/black) and [Isort](https://pypi.org/project/isort/). You have the following commands to your disposal:\n\n```bash\n$ make format.black # Apply Black on every file\n$ make format.isort # Apply Isort on every file\n```\n\n## Swagger\n\nYour API needs a description of it's routes and how to interact with them.\nYou can easily do that with the swagger package included in the starter kit.\nSimply add a docstring to the resources of your API like in the `user` example.\nThe API description will be available [here](http://127.0.0.1:3000/application/spec).\nThe Swagger UI will be available [here](http://127.0.0.1:3000/apidocs/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantkahn%2Fflask-api-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantkahn%2Fflask-api-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantkahn%2Fflask-api-starter-kit/lists"}