Initial commit

.env.example

@@ -0,0 +1,24 @@
+# A complete list of supported variables is included in the documentation.
+
+# Set to any non-empty value to disable token authentication.
+DISABLE_AUTH=
+
+# An email server to use when sending emails. For SendGrid, use "smtp.sendgrid.net". For Gmail use "smtp.googlemail.com".
+MAIL_SERVER=
+
+# The port in which the email server listens for clients. For SendGrid or Gmail, use 587.
+MAIL_PORT=
+
+# Set to any non-empty string to send emails via TLS. Required for both SendGrid and Gmail.
+MAIL_USE_TLS=
+
+# The username for the email sender's account, if required by the server.
+# For SendGrid, use "apikey". For Gmail, use your Google username.
+MAIL_USERNAME=
+
+# The password for the email sender's account, if required by the server.
+# For SendGrid, use your API Key. For Gmail, use your Google password (you will need to allow less secure apps in your Google account settings).
+MAIL_PASSWORD=
+
+# The sender that appears in all emails sent by the application.
+MAIL_DEFAULT_SENDER=

.flaskenv

@@ -0,0 +1,2 @@
+FLASK_APP=microblog.py
+FLASK_ENV=development

.gitignore

@@ -0,0 +1,132 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# database
+*.sqlite

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.10-slim
+
+ENV FLASK_APP microblog.py
+ENV FLASK_ENV production
+
+COPY requirements.txt ./
+RUN pip install -r requirements.txt
+
+COPY api api
+COPY migrations migrations
+COPY microblog.py config.py boot.sh ./
+
+EXPOSE 5000

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Miguel Grinberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Procfile

@@ -0,0 +1 @@
+web: gunicorn --access-logfile - --error-logfile - microblog:app

README.md

@@ -0,0 +1,75 @@
+# microblog-api
+An modern (as of 2022) Flask API back end.
+
+## Deploy to Heroku
+
+Click the button below to deploy the application directly to your Heroku
+account.
+
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/miguelgrinberg/microblog-api/tree/heroku)
+
+## Deploy on your Computer
+
+### Setup
+
+Follow these steps if you want to run this application on your computer, either
+in a Docker container or as a standalone Python application.
+
+```bash
+git clone https://github.com/miguelgrinberg/microblog-api
+cd microblog-api
+cp .env.example .env
+```
+
+Open the new `.env` file and enter values for the configuration variables.
+
+### Run with Docker
+
+To start:
+
+```bash
+docker-compose up -d
+```
+
+The application runs on port 5000 on your Docker host. You can access the API
+documentation on the `/docs` URL (i.e. `http://localhost:5000/docs` if you are
+running Docker locally).
+
+To populate the database with some randomly generated data:
+
+```bash
+docker-compose run --rm microblog-api bash -c "flask fake users 10 && flask fake posts 100"
+```
+
+To stop the application:
+
+```bash
+docker-compose down
+```
+
+### Run locally
+
+Set up a Python 3 virtualenv and install the dependencies on it:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+Create the database and populate it with some randomly generated data:
+
+```bash
+flask db upgrade
+flask fake users 10
+flask fake posts 100
+```
+
+Run the application with the Flask development web server:
+
+```bash
+flask run
+```
+
+The application runs on `localhost:5000`. You can access the API documentation
+at `http://localhost:5000/docs`.

api/__init__.py

@@ -0,0 +1,121 @@
+"""
+Welcome to the documentation for the Microblog API!
+
+This project is written in Python, with the
+[Flask](https://flask.palletsprojects.com/) web framework. This documentation
+is generated automatically from the
+[project's source code](https://github.com/miguelgrinberg/microblog-api) using
+the [APIFairy](https://github.com/miguelgrinberg/apifairy) Flask extension.
+
+## Introduction
+
+Microblog-API is an easy to use web API for creating microblogs. It is an ideal
+project to use when learning a front end framework, as it provides a fully
+implemented back end that you can integrate against.
+
+Microblog API provides all the base features required to implement a
+microblogging project:
+
+- User registration, login and logout
+- Password recovery flow with reset emails
+- Post creation and deletion
+- Follow and unfollow users
+- Timeline with posts from followed users
+- Pagination of collections
+- Option to disable authentication
+
+## Configuration
+
+If you are running Microblog API yourself while developing your front end,
+there are a number of environment variables that you can set to configure its
+behavior. The variables can be defined directly in the environment or in a
+`.env` file in the project directory. The following table lists all the
+environment variables that are currently used:
+
+| Environment Variable | Default | Description |
+| - | - | - |
+| `SECRET_KEY` | `top-secret!` | A secret key used when signing tokens. |
+| `DATABASE_URL`  | `sqlite:///db.sqlite` | The database URL, as defined by the [SQLAlchemy](https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls) framework. |
+| `SQL_ECHO` | not defined | Whether to echo SQL statements to the console for debugging purposes. |
+| `DISABLE_AUTH` | not defined | Whether to disable authentication. When running with authentication disabled, the user is assumed to be logged as the first user in the database. |
+| `ACCESS_TOKEN_EXPIRATION` | `60` (1 hour) | The number of minutes an access token is valid for. |
+| `REFRESH_TOKEN_EXPIRATION` | `1440` (24 hours) | The number of minutes a refresh token is valid for. |
+| `RESET_TOKEN_EXPIRATION` | `15` (15 minutes) | The number of minutes a reset token is valid for. |
+| `DOCS_UI` | `elements` | The UI library to use for the documentation. Allowed values are `swagger_ui`, `redoc`, `rapidoc` and `elements`. |
+| `MAIL_SERVER` | `localhost` | The mail server to use for sending emails. |
+| `MAIL_PORT` | `25` | The port to use for sending emails. |
+| `MAIL_USE_TLS` | not defined | Whether to use TLS when sending emails. |
+| `MAIL_USERNAME` | not defined | The username to use for sending emails. |
+| `MAIL_PASSWORD` | not defined | The password to use for sending emails. |
+| `MAIL_DEFAULT_SENDER` | `[email protected]` | The default sender to use for emails. |
+
+## Authentication
+
+The authentication flow for this API is based on *access* and *refresh*
+tokens.
+
+To obtain an access and refresh token pair, the client must send a `POST`
+request to the `/api/tokens` endpoint, passing the username and password of
+the user in a `Authorization` header, according to HTTP Basic Authentication
+scheme.
+
+Most endpoints in this API are authenticated with the access token, passed
+also in the `Authorization` header, but this time using the `Bearer` scheme.
+
+Access tokens are valid for one hour (by default) from the time they are
+issued. When the access token is expired, the client can renew it using the
+refresh token. For this, the client must send a `PUT` request to the
+`/api/tokens` endpoint, passing both the expired access token and the still
+valid refresh token in the body of the request. The response to this request
+will include a new token pair. Refresh tokens have a default validity period of
+24 hours, and can only be used to renew the access token that was returned with
+it.
+
+A refreshed access token can be used exactly as an originally issued one, but
+refreshed tokens are restricted from performance sensitive operations such as
+changing the user's password for security purposes.
+
+All authentication failures are handled with a `401` status code in the
+response.
+
+### Password Resets
+
+This API also supports a password reset flow, to help users who forget their
+passwords. To issue a password request, the client must send a `POST` request
+to `/api/tokens/reset`, passing the user's email in the body of the request.
+The user will receive a password reset link by email, which is the request's
+[Referrer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer)
+URL, with an added `token` query string argument set to an email reset token,
+with a validity of 15 minutes.
+
+When the user clicks on the password reset link, the client application must
+capture the `token` query string argument and send it in a `PUT` request to
+`/api/tokens/reset`, along with the new password chosen by the user.
+
+## Errors
+
+All errors returned by this API use the following JSON structure:
+
+```json
+{
+    "code": <numeric error code>,
+    "message": <short error message>,
+    "description": <longer error description>,
+}
+```
+
+In the case of schema validation errors, an `errors` property is also returned,
+containing a detailed list of validation errors found in the submitted request:
+
+```json
+{
+    "code": <error code>,
+    "message": <error message>,
+    "description": <error description>,
+    "errors": [ <error details>, ... ]
+}
+```
+
+"""  # noqa: E501
+
+from api.app import create_app, db, ma  # noqa: F401