|
| 1 | + |
| 2 | +# Flask REST API Boilerplate |
| 3 | + |
| 4 | +A better boilerplate for RESTful APIs using Flask. |
| 5 | + |
| 6 | +If you have ever used Flask to build REST APIs, you'd know how cumbersome it can get. This repository aims to change that. |
| 7 | + |
| 8 | +This repository: |
| 9 | + |
| 10 | +1. Aims to fix common pain points with building REST APIs with Flask. |
| 11 | +2. Uses pluggable views, blueprints, decorators and pydantic to modularize application and avoid repetition commonly associated with CRUD calls (DRY principle). [See how fast and easy it is to write APIs using this boilerplate](#guide-for-extending-this-boilerplate). |
| 12 | +3. Doesn't use any of the Flask-RESTFul (Latest release: 2014), Flask-Restless (Latest release: 2016), or any similar spin-offs of Flask which eventually died out. Instead it relies only on core Flask. This has a huge advantage of always having the latest version of Flask for your application. |
| 13 | + |
| 14 | + |
| 15 | +#### Tech Stack: |
| 16 | + |
| 17 | + - **Web framework:** Flask |
| 18 | + - **ORM:** SQLAlchemy |
| 19 | + - **Database:** PostgresSQL |
| 20 | + - **Parsing/Validation:** Pydantic |
| 21 | + - **Containerization:** Docker |
| 22 | + - **Async-Task Queue:** Celery |
| 23 | + - **Message-Broker:** RabbitMQ |
| 24 | + - **WSGI Server:** Gunicorn |
| 25 | + - **Reverse Proxy Server:** NGINX |
| 26 | + - **Documentation:** Swagger-UI |
| 27 | + |
| 28 | +#### Features: |
| 29 | + |
| 30 | +* Containerized Docker build |
| 31 | +* Separate docker services for database (**db**), message-broker (**celery-broker**), API (**web**), and documentation (**swagger-ui**). |
| 32 | +* Ability to run this API with a different database, or broker, or documentation service. As easy as editing docker-compose and .env files. |
| 33 | +* Separate environments and configs for Development, Testing, and Production. |
| 34 | +* RESTful API documentation via Swagger and visualization with Swagger UI. |
| 35 | +* Easy to write different API versions. |
| 36 | +* Authentication via JWT. |
| 37 | +* Email Verification. |
| 38 | +* OAuth for Github and Facebook. |
| 39 | +* Parsing and Validation via Pydantic. |
| 40 | +* Database entities integrated with SQLAlchemy. |
| 41 | +* Tests covering each of the REST API services, with code coverage. |
| 42 | + |
| 43 | +## Contents |
| 44 | + |
| 45 | +* [Get Started](#get-started) |
| 46 | +* [Testing and Coverage](#testing-and-coverage) |
| 47 | +* [RESTful endpoints](#restful-endpoints) |
| 48 | +* [Guide for extending this Boilerplate](#guide-for-extending-this-boilerplate) |
| 49 | + |
| 50 | +## Get Started |
| 51 | + |
| 52 | +#### Requirements |
| 53 | + |
| 54 | +* Docker |
| 55 | +* Docker Compose |
| 56 | +* Docker Machine |
| 57 | +* Other dependencies are listed in `requirements.txt` and are installed automatically. |
| 58 | + |
| 59 | +Get docker: https://docs.docker.com/get-docker/ |
| 60 | + |
| 61 | +Clone all the project from this repository and move to repository folder. |
| 62 | + |
| 63 | +Rename `.env.dev.sample` file to `.env.dev`. All environment variables are set from this file. |
| 64 | + |
| 65 | +Make sure you set the following environment variables: |
| 66 | + |
| 67 | + GITHUB_CLIENT_ID |
| 68 | + GITHUB_CLIENT_SECRET |
| 69 | + FACEBOOK_CLIENT_ID |
| 70 | + FACEBOOK_CLIENT_SECRET |
| 71 | + MAIL_SERVER |
| 72 | + MAIL_PORT |
| 73 | + MAIL_USERNAME |
| 74 | + MAIL_PASSWORD |
| 75 | + MAIL_DEFAULT_SENDER |
| 76 | + |
| 77 | +Build the images and run the containers. |
| 78 | +```bash |
| 79 | +docker-compose up --build |
| 80 | +``` |
| 81 | +or if you want to run it in detached (background) mode: |
| 82 | +```bash |
| 83 | +docker-compose up -d --build |
| 84 | +``` |
| 85 | +Make sure all containers are running: |
| 86 | +```bash |
| 87 | +docker-compose ps |
| 88 | +``` |
| 89 | +```bash |
| 90 | +web |
| 91 | +db |
| 92 | +broker |
| 93 | +docs |
| 94 | +``` |
| 95 | +Check swagger API documentation through http://localhost:8000. |
| 96 | +API is available under http://localhost:5000/v1. |
| 97 | +You can change the default ports in `docker-compose.yml` file. |
| 98 | + |
| 99 | +#### Database commands |
| 100 | + |
| 101 | +Create all development db tables: |
| 102 | + |
| 103 | +```docker |
| 104 | +docker-compose exec web python manage.py create_db |
| 105 | +``` |
| 106 | +Recreate all development db tables: |
| 107 | + |
| 108 | +```docker |
| 109 | +docker-compose exec web python manage.py recreate_db |
| 110 | +``` |
| 111 | +Populate seed data into db: |
| 112 | + |
| 113 | +```docker |
| 114 | +docker-compose exec web python manage.py seed_db |
| 115 | +``` |
| 116 | +Want to reset everything? |
| 117 | +```docker |
| 118 | +docker-compose down -v |
| 119 | +docker-compose up --build |
| 120 | +``` |
| 121 | + |
| 122 | +## Testing and Coverage |
| 123 | + |
| 124 | +Finally test that everything works by executing the following curl command that tries to logged in using a default user created in the seed_db command: (default admin **email: ** [email protected], **password: ** password). |
| 125 | + |
| 126 | +```bash |
| 127 | +curl -X POST "http://0.0.0.0:5000/v1/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"email\":\"[email protected]\",\"password\":\"password\"}" |
| 128 | +``` |
| 129 | +> You should get a response like this: |
| 130 | +```bash |
| 131 | +{ |
| 132 | + "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzAzODEzMTUsImlhdCI6MTUyNzc4OTMxNSwic3ViIjoxfQ.Dzf017g5Qf9Mi24AH-0X3womGW2koTY3c3cCO5p1djE", |
| 133 | + "message": "Successfully logged in." |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +Run tests using: |
| 138 | +```docker |
| 139 | +docker-compose exec web python manage.py test |
| 140 | +``` |
| 141 | +> You should see an output like this: |
| 142 | +```bash |
| 143 | +... |
| 144 | +... |
| 145 | +Ensure encoding auth token works ... ok |
| 146 | +test_model_user_passwords_are_random (test_model_user.TestUserModel) |
| 147 | +Ensure passwords are randomly hashed ... ok |
| 148 | +test_user_get (test_user_user.TestUserBlueprint) |
| 149 | +Ensure get single user behaves correctly. ... ok |
| 150 | + |
| 151 | +---------------------------------------------------------------------- |
| 152 | +Ran 80 tests in 13.335s |
| 153 | + |
| 154 | +OK |
| 155 | +``` |
| 156 | + |
| 157 | +Run coverage using: |
| 158 | +```docker |
| 159 | +docker-compose exec web python manage.py cov |
| 160 | +``` |
| 161 | + |
| 162 | + |
| 163 | +## RESTful endpoints |
| 164 | +Different roles: USER, ADMIN. |
| 165 | + |
| 166 | +### Authentication |
| 167 | +| Endpoint | HTTP Method | Result | |
| 168 | +|:---|:---:|---| |
| 169 | +| `/auth/register` | `POST` | Registers a new user | |
| 170 | +| `/auth/login` | `POST` | Login the user | |
| 171 | +| `/auth/logout` | `GET` | User logout | |
| 172 | +| `/auth/status` | `GET` | Returns the logged in user's status | |
| 173 | +| `/auth/password_recovery` | `POST` | Creates a password_recovery_hash and sends email to user | |
| 174 | +| `/auth/password_reset` | `PUT` | Reset user password | |
| 175 | +| `/auth/password_change` | `PUT` | Changes user password | |
| 176 | +> Endpoints implementation can be found under [/project/api/v1/auth/core.py](./services/web/project/api/v1/auth/core.py). |
| 177 | +
|
| 178 | +### Social Auth |
| 179 | +| Endpoint | HTTP Method | Result | |
| 180 | +|:---|:---:|---| |
| 181 | +| `/auth/facebook/login` | `GET` | Redirects user to Facebook to authenticate and returns API access token upon success. Works for registration and login. | |
| 182 | +| `/auth/github/login` | `GET` | Redirects user to Github to authenticate and returns API access token upon success. Works for registration and login. | |
| 183 | +> Endpoints implementation can be found under [/project/api/v1/auth/social.py](./services/web/project/api/v1/auth/social.py). |
| 184 | +
|
| 185 | +### Email Verification |
| 186 | +|Endpoint| HTTP Method | Result | |
| 187 | +|:---|:---:|---| |
| 188 | +| `/email_verification` | `PUT` | Creates a email_token_hash and sends email with token to user | |
| 189 | +| `/email_verification/<token>` | `GET` | Verifies email and sets email verified date | |
| 190 | +> Endpoints implementation can be found under [/project/api/v1/auth/email_verification.py](./services/web/project/api/v1/auth/email_verification.py). |
| 191 | +
|
| 192 | +### Users |
| 193 | +**Requires role:** ADMIN |
| 194 | + |
| 195 | +| Endpoint | HTTP Method | Result | |
| 196 | +|:---|:---:|---| |
| 197 | +| `/users` | `POST` | Adds a new user | |
| 198 | +| `/users` | `GET` | Gets all users | |
| 199 | +| `/users/{user_id}` | `GET` | Gets the given user | |
| 200 | +| `/users/{user_id}` | `PUT` | Updates the given user | |
| 201 | +| `/users/{user_id}` | `DELETE` | Deletes the given user | |
| 202 | +> Endpoints implementation can be found under [/project/api/v1/admin/users.py](./services/web/project/api/v1/admin/users.py). |
| 203 | +
|
| 204 | +### User |
| 205 | +**Requires role:** USER |
| 206 | + |
| 207 | +| Endpoint | HTTP Method | Result | |
| 208 | +|:---|:---:|---| |
| 209 | +| `/user` | `GET` | Get user info | |
| 210 | +> Endpoints implementation can be found under [/project/api/v1/user/user.py](./services/web/project/api/v1/user/user.py). |
| 211 | +
|
| 212 | + |
| 213 | +For detailed documentation including request/response data, please check the Swagger-UI at http://localhost:8000. |
| 214 | + |
| 215 | +## Guide for extending this Boilerplate |
| 216 | +Extending this boilerplate is very simple. |
| 217 | +**Example:** You need to add a new API called *items* which lets normal users CRUD on their items. |
| 218 | +1. Create `item` database model in [project/models](./services/web/project/models/). |
| 219 | +2. Create `items.py` in [api/v1/user/](./services/web/project/api/v1/user/) folder. |
| 220 | + 1. See [this](./services/web/project/api/v1/admin/users.py) as an example of how-to. |
| 221 | + 2. Create an ItemsAPI class and extend this class from BaseAPI and MethodView classes. |
| 222 | + 3. Overwrite the CRUD methods inherited from BaseAPI. In most cases, you'll just need to use a one-liner to call the base class method with your validation model, and db class. |
| 223 | +3. Create `items.py` in [api/v1/validations/user/](./services/web/project/api/v1/validations/user/) folder. |
| 224 | + 1. See [this](./services/web/project/api/v1/validations/admin/users.py) as an example of how-to. |
| 225 | + 2. You will need knowledge of [pydantic](https://pydantic-docs.helpmanual.io/) to write validation models. |
| 226 | +4. Create a new test file `test_user_items.py` (convention for this project) in [services/web/tests](./services/web/tests) and write your tests. |
| 227 | + |
| 228 | +**In a nutshell**, your request data is forwarded to BaseAPI, and for POST/PUT methods, you provide validation classes which map to attributes directly in database models. Any fields you provide in your validation classes (which already exist in DB models), are automatically mapped. Moreover, the data is also validated for its type, as well as any custom validators that you define. |
| 229 | + |
| 230 | +For admins, you will follow the same procedure, but instead use the admin folder under api/v1 and api/v1/validations. |
| 231 | + |
| 232 | +Feel free to nudge me if you need help. I'll also improve this writeup pretty soon. |
0 commit comments