Merge pull request #259 from realpython/fastapi-url-shortener

Add FastAPI URL Shortener

Author: bzaczynski

fastapi-url-shortener/README.md

@@ -0,0 +1,67 @@
+# FastAPI URL Shortener
+
+## Install the Project
+
+1. Create a Python virtual environment
+
+```sh
+$ python -m venv venv
+$ source venv/bin/activate
+(venv) $
+```
+
+2. Install the requirements
+
+```
+(venv) $ python -m pip install -r requirements.txt
+```
+
+## Run the Project
+
+You can run the project with this command in your terminal:
+
+```sh
+(venv) $ uvicorn shortener_app.main:app --reload
+```
+
+Your server will reload automacially when you change a file.
+
+## Verify Your Environment Variables
+
+The project provides default environment settings in [`shortener_app/config.py`](shortener_app/config.py).
+While you can use the default settings, [it's recommended](https://12factor.net/config) to create a `.env` file to store your settings outside of your production code. E.g.:
+
+```config
+# .env
+ENV_NAME="Development"
+BASE_URL="http://url.shortener"
+DB_URL="sqlite:///./test_database.db"
+```
+
+With an `.env` file that contains the `ENV_NAME` variable with the value `"Development"` you can verify if your external `.env` file loads correctly:
+
+```pycon
+>>> from shortener_app.config import get_settings
+>>> get_settings().env_name
+... loading Settings
+'Development'
+```
+
+To get an overview of the environment variables you can set, check the [`shortener_app/config.py`](shortener_app/config.py) file.
+
+> ☝️ **Note:** You should never add the `.env` file to your version control system. 
+
+## Visit the Documentation
+
+When the project is running you can visit the documentation in your browser:
+
+- http://127.0.0.1:8000/docs
+- http://127.0.0.1:8000/redoc
+
+## About the Author
+
+Philipp Acsany - Email: [email protected]
+
+## License
+
+Distributed under the MIT license. See `LICENSE` in the root directory of this `materials` repo for more information.

fastapi-url-shortener/source_code_final/README.md

@@ -0,0 +1,67 @@
+# FastAPI URL Shortener
+
+## Install the Project
+
+1. Create a Python virtual environment
+
+```sh
+$ python -m venv venv
+$ source venv/bin/activate
+(venv) $
+```
+
+2. Install the requirements
+
+```
+(venv) $ python -m pip install -r requirements.txt
+```
+
+## Run the Project
+
+You can run the project with this command in your terminal:
+
+```sh
+(venv) $ uvicorn shortener_app.main:app --reload
+```
+
+Your server will reload automacially when you change a file.
+
+## Verify Your Environment Variables
+
+The project provides default environment settings in [`shortener_app/config.py`](shortener_app/config.py).
+While you can use the default settings, [it's recommended](https://12factor.net/config) to create a `.env` file to store your settings outside of your production code. E.g.:
+
+```config
+# .env
+ENV_NAME="Development"
+BASE_URL="http://url.shortener"
+DB_URL="sqlite:///./test_database.db"
+```
+
+With an `.env` file that contains the `ENV_NAME` variable with the value `"Development"` you can verify if your external `.env` file loads correctly:
+
+```pycon
+>>> from shortener_app.config import get_settings
+>>> get_settings().env_name
+... loading Settings
+'Development'
+```
+
+To get an overview of the environment variables you can set, check the [`shortener_app/config.py`](shortener_app/config.py) file.
+
+> ☝️ **Note:** You should never add the `.env` file to your version control system. 
+
+## Visit the Documentation
+
+When the project is running you can visit the documentation in your browser:
+
+- http://127.0.0.1:8000/docs
+- http://127.0.0.1:8000/redoc
+
+## About the Author
+
+Philipp Acsany - Email: [email protected]
+
+## License
+
+Distributed under the MIT license. See `LICENSE` in the root directory of this `materials` repo for more information.

fastapi-url-shortener/source_code_final/requirements.txt

@@ -0,0 +1,16 @@
+anyio==3.6.0
+asgiref==3.5.1
+click==8.1.3
+decorator==5.1.1
+fastapi==0.75.0
+h11==0.13.0
+idna==3.3
+pydantic==1.9.0
+python-dotenv==0.19.2
+six==1.16.0
+sniffio==1.2.0
+SQLAlchemy==1.4.32
+starlette==0.17.1
+typing_extensions==4.2.0
+uvicorn==0.17.6
+validators==0.18.2

fastapi-url-shortener/source_code_final/shortener_app/__init__.py

@@ -0,0 +1,19 @@
+from functools import lru_cache
+
+from pydantic import BaseSettings
+
+
+class Settings(BaseSettings):
+    env_name: str = "Local"
+    base_url: str = "http://localhost:8000"
+    db_url: str = "sqlite:///./shortener.db"
+
+    class Config:
+        env_file = ".env"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    settings = Settings()
+    print(f"Loading settings for: {settings.env_name}")
+    return settings

fastapi-url-shortener/source_code_final/shortener_app/config.py

@@ -0,0 +1,49 @@
+from sqlalchemy.orm import Session
+
+from . import keygen, models, schemas
+
+
+def create_db_url(db: Session, url: schemas.URLBase) -> models.URL:
+    key = keygen.create_unique_random_key(db)
+    secret_key = f"{key}_{keygen.create_random_key(length=8)}"
+    db_url = models.URL(
+        target_url=url.target_url, key=key, secret_key=secret_key
+    )
+    db.add(db_url)
+    db.commit()
+    db.refresh(db_url)
+    return db_url
+
+
+def get_db_url_by_key(db: Session, url_key: str) -> models.URL:
+    return (
+        db.query(models.URL)
+        .filter(models.URL.key == url_key, models.URL.is_active)
+        .first()
+    )
+
+
+def get_db_url_by_secret_key(db: Session, secret_key: str) -> models.URL:
+    return (
+        db.query(models.URL)
+        .filter(models.URL.secret_key == secret_key, models.URL.is_active)
+        .first()
+    )
+
+
+def update_db_clicks(db: Session, db_url: schemas.URL) -> models.URL:
+    db_url.clicks += 1
+    db.commit()
+    db.refresh(db_url)
+    return db_url
+
+
+def deactivate_db_url_by_secret_key(
+    db: Session, secret_key: str
+) -> models.URL:
+    db_url = get_db_url_by_secret_key(db, secret_key)
+    if db_url:
+        db_url.is_active = False
+        db.commit()
+        db.refresh(db_url)
+    return db_url

fastapi-url-shortener/source_code_final/shortener_app/crud.py

@@ -0,0 +1,11 @@
+from sqlalchemy import create_engine
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+
+from .config import get_settings
+
+engine = create_engine(
+    get_settings().db_url, connect_args={"check_same_thread": False}
+)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+Base = declarative_base()

fastapi-url-shortener/source_code_final/shortener_app/database.py

@@ -0,0 +1,18 @@
+import secrets
+import string
+
+from sqlalchemy.orm import Session
+
+from . import crud
+
+
+def create_random_key(length: int = 5) -> str:
+    chars = string.ascii_uppercase + string.digits
+    return "".join(secrets.choice(chars) for _ in range(length))
+
+
+def create_unique_random_key(db: Session) -> str:
+    key = create_random_key()
+    while crud.get_db_url_by_key(db, key):
+        key = create_random_key()
+    return key

fastapi-url-shortener/source_code_final/shortener_app/keygen.py

@@ -0,0 +1,94 @@
+import validators
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.responses import RedirectResponse
+from sqlalchemy.orm import Session
+from starlette.datastructures import URL
+
+from . import crud, models, schemas
+from .database import SessionLocal, engine
+from .config import get_settings
+
+app = FastAPI()
+models.Base.metadata.create_all(bind=engine)
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def get_admin_info(db_url: models.URL) -> schemas.URLInfo:
+    base_url = URL(get_settings().base_url)
+    admin_endpoint = app.url_path_for(
+        "administration info", secret_key=db_url.secret_key
+    )
+    db_url.url = str(base_url.replace(path=db_url.key))
+    db_url.admin_url = str(base_url.replace(path=admin_endpoint))
+    return db_url
+
+
+def raise_bad_request(message):
+    raise HTTPException(status_code=400, detail=message)
+
+
+def raise_not_found(request):
+    message = f"URL '{request.url}' doesn't exist"
+    raise HTTPException(status_code=404, detail=message)
+
+
+@app.get("/")
+def read_root():
+    return "Welcome to the URL shortener API :)"
+
+
+@app.post("/url", response_model=schemas.URLInfo)
+def create_url(url: schemas.URLBase, db: Session = Depends(get_db)):
+    if not validators.url(url.target_url):
+        raise_bad_request(message="Your provided URL is not valid")
+
+    db_url = crud.create_db_url(db=db, url=url)
+    return get_admin_info(db_url)
+
+
+@app.get("/{url_key}")
+def forward_to_target_url(
+    url_key: str, request: Request, db: Session = Depends(get_db)
+):
+    if db_url := crud.get_db_url_by_key(db=db, url_key=url_key):
+        crud.update_db_clicks(db=db, db_url=db_url)
+        return RedirectResponse(db_url.target_url)
+    else:
+        raise_not_found(request)
+
+
+@app.get(
+    "/admin/{secret_key}",
+    name="administration info",
+    response_model=schemas.URLInfo,
+)
+def get_url_info(
+    secret_key: str, request: Request, db: Session = Depends(get_db)
+):
+    if db_url := crud.get_db_url_by_secret_key(db, secret_key=secret_key):
+        return get_admin_info(db_url)
+    else:
+        raise_not_found(request)
+
+
+@app.delete("/admin/{secret_key}")
+def delete_url(
+    secret_key: str, request: Request, db: Session = Depends(get_db)
+):
+    if db_url := crud.deactivate_db_url_by_secret_key(
+        db, secret_key=secret_key
+    ):
+        message = (
+            f"Successfully deleted shortened URL for '{db_url.target_url}'"
+        )
+        return {"detail": message}
+    else:
+        raise_not_found(request)

fastapi-url-shortener/source_code_final/shortener_app/main.py

@@ -0,0 +1,14 @@
+from sqlalchemy import Boolean, Column, Integer, String
+
+from .database import Base
+
+
+class URL(Base):
+    __tablename__ = "urls"
+
+    id = Column(Integer, primary_key=True)
+    key = Column(String, unique=True, index=True)
+    secret_key = Column(String, unique=True, index=True)
+    target_url = Column(String, index=True)
+    is_active = Column(Boolean, default=True)
+    clicks = Column(Integer, default=0)