Initial commit

Author: David-Lor

.dockerignore

@@ -0,0 +1,7 @@
+.git/
+.github/
+.pytest_cache/
+*pycache*
+.idea/
+.vscode/
+.env

.github/workflows/test.yaml

@@ -0,0 +1,30 @@
+name: Test
+on:
+  - push
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }} @ ubuntu-latest
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.6"
+          - "3.7"
+          - "3.8"
+    services:
+      mongodb:
+        image: mongo:latest
+        ports:
+          - 27017:27017
+    steps:
+      - uses: actions/checkout@master
+      - name: Setup Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+      - name: Install requirements
+        run: make install-all-requirements
+      - name: Test
+        run: make test

.gitignore

@@ -0,0 +1,4 @@
+.idea/
+.vscode/
+*pycache*/
+.env

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.8
+
+RUN useradd -ms /bin/bash user
+USER user
+
+COPY . /home/user/app/
+WORKDIR /home/user/app
+RUN pip install --user -r requirements.txt
+
+CMD make run

LICENSE.md

@@ -0,0 +1,6 @@
+Copyright 2020 David Lorenzo
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

Makefile

@@ -0,0 +1,29 @@
+.DEFAULT_GOAL := help
+
+install-requirements: ## pip install requirements for app
+	pip install -r requirements.txt
+
+install-test-requirements: ## pip install requirements for tests
+	pip install -r requirements-test.txt
+
+install-all-requirements: ## pip install requirements for app & tests
+	make install-requirements
+	make install-test-requirements
+
+test: ## run tests
+	pytest -sv .
+
+run: ## python run app
+	python .
+
+run-docker: ## start running through docker-compose
+	docker-compose up
+
+run-docker-background: ## start running through docker-compose, detached
+	docker-compose up -d
+
+teardown-docker: ## remove from docker through docker-compose
+	docker-compose down
+
+help: ## show this help.
+	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'

README.md

@@ -0,0 +1,53 @@
+# FastAPI + Pydantic + MongoDB REST API Example
+
+Sample API using FastAPI, Pydantic models and settings, and MongoDB as database - non-async.
+
+The API works with a single entity, "Person" (or "People" in plural) that gets stored on a single Mongo database and collection.
+
+## Endpoints
+
+- GET `/people` - list all available persons
+- GET `/people/{person_id}` - get a single person by its unique ID
+- POST `/people` - create a new person
+- PATCH `/people/{person_id}` - update an existing person
+- DELETE `/people/{person_id}` - delete an existing person
+
+## Project structure (modules)
+
+- `app.py`: initialization of FastAPI and all the routes used by the API. On APIs with more endpoints and different entities, would be better to split the routes in different modules by their context or entity.
+- `models`: definition of all model classes. As we are using MongoDB, we can use the same JSON schema for API request/response and storage. However, different classes for the same entity are required, depending on the context:
+    - `person_update.py`: model used as PATCH request body. Includes all the fields that can be updated, set as optional.
+    - `person_create.py`: model used as POST request body. Includes all the fields from the Update model, but all those fields that are required on Create, must be re-declared (in type and Field value).
+    - `person_read.py`: model used as GET and POST response body. Includes all the fields from the Create model, plus the person_id (which comes from the _id field in Mongo document) and the age (calculated from the date of birth, if any).
+    - `person_address.py`: part of the Person model, address attribute.
+    - `common.py`: definition of the common BaseModel, from which all the model classes inherit, directly or indirectly.
+    - `fields.py`: definition of Fields, which are the values of the models attributes. Their main purpose is to complete the OpenAPI documentation by providing a description and examples. Fields are declared outside the classes because of the re-declaration required between Update and Create models.
+- `database.py`: initialization of MongoDB client. Actually is very short as Mongo/pymongo do not require to pre-connecting to Mongo or setup the database/collection, but with other databases (like SQL-like using SQLAlchemy) this can get more complex.
+- `exceptions.py`: custom exceptions, that can be translated to JSON responses the API can return to clients (mainly if a Person does not exist or already exists).
+- `middlewares.py`: the Request Handler middleware catches the exceptions raised while processing requests, and tries to translate them into responses given to the clients.
+- `repositories.py`: methods that interact with the Mongo database to read or write Person data. These methods are directly called from the route handlers.
+- `settings.py`: load of application settings through environment variables or dotenv file, using Pydantic's BaseSettings classes.
+- `utils.py`: misc helper functions.
+- `tests`: acceptance+integration tests, ran directly against a running API and real Mongo database.
+
+## Requirements
+
+- Python >= 3.6
+- Requirements listed on [requirements.txt](requirements.txt)
+- Running MongoDB server
+
+## make tools
+
+```bash
+# Install requirements
+make install-requirements
+
+# Run the app (available at http://localhost:5000/...)
+make run
+
+# Install test requirements
+make install-test-requirements
+
+# Run the tests
+make test
+```

__main__.py

@@ -0,0 +1,3 @@
+from people_api import run
+
+run()

docker-compose.yml

@@ -0,0 +1,19 @@
+version: '3'
+
+services:
+  people_api:
+    build:
+      context: .
+    ports:
+      - 5000:5000
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /etc/timezone:/etc/timezone:ro
+    environment:
+      - MONGO_URI=mongodb://mongodb:27017
+
+  mongodb:
+    image: mongo:latest
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+      - /etc/timezone:/etc/timezone:ro

people_api/__init__.py

@@ -0,0 +1 @@
+from .app import app, run

people_api/app.py

@@ -0,0 +1,84 @@
+"""APP
+FastAPI app definition, initialization and definition of routes
+"""
+
+# # Installed # #
+import uvicorn
+from fastapi import FastAPI
+from fastapi import status as statuscode
+
+# # Package # #
+from .models import *
+from .repositories import PeopleRepository
+from .middlewares import request_handler
+from .settings import api_settings as settings
+
+__all__ = ("app", "run")
+
+
+app = FastAPI(
+    title=settings.title
+)
+app.middleware("http")(request_handler)
+
+
+@app.get(
+    "/people",
+    response_model=PeopleRead,
+    description="List all the available persons",
+    tags=["people"]
+)
+def _list_people():
+    # TODO Filters
+    return PeopleRepository.list()
+
+
+@app.get(
+    "/people/{person_id}",
+    response_model=PersonRead,
+    description="Get a single person by its unique ID",
+    tags=["people"]
+)
+def _get_person(person_id: str):
+    return PeopleRepository.get(person_id)
+
+
+@app.post(
+    "/people",
+    description="Create a new person",
+    response_model=PersonRead,
+    status_code=statuscode.HTTP_201_CREATED,
+    tags=["people"]
+)
+def _create_person(create: PersonCreate):
+    return PeopleRepository.create(create)
+
+
+@app.patch(
+    "/people/{person_id}",
+    description="Update a single person by its unique ID, providing the fields to update",
+    status_code=statuscode.HTTP_204_NO_CONTENT,
+    tags=["people"]
+)
+def _update_person(person_id: str, update: PersonUpdate):
+    PeopleRepository.update(person_id, update)
+
+
+@app.delete(
+    "/people/{person_id}",
+    description="Delete a single person by its unique ID",
+    status_code=statuscode.HTTP_204_NO_CONTENT,
+    tags=["people"]
+)
+def _delete_person(person_id: str):
+    PeopleRepository.delete(person_id)
+
+
+def run():
+    """Run the API using Uvicorn"""
+    uvicorn.run(
+        app,
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower()
+    )

people_api/database.py

@@ -0,0 +1,15 @@
+"""DATABASE
+MongoDB database initialization
+"""
+
+# # Installed # #
+from pymongo import MongoClient
+from pymongo.collection import Collection
+
+# # Package # #
+from .settings import mongo_settings as settings
+
+__all__ = ("client", "collection")
+
+client = MongoClient(settings.uri)
+collection: Collection = client[settings.database][settings.collection]

people_api/exceptions.py

@@ -0,0 +1,42 @@
+"""EXCEPTIONS
+Custom exceptions with responses
+"""
+
+# # Installed # #
+from fastapi.responses import JSONResponse
+from fastapi import status as statuscode
+
+__all__ = (
+    "EntityError", "NotFound",
+    "PersonNotFound"
+)
+
+
+class EntityError(Exception):
+    """Base errors for entities, uniquely identified"""
+    message = "Entity error"
+    code = statuscode.HTTP_500_INTERNAL_SERVER_ERROR
+
+    def __init__(self, identifier):
+        self.id = identifier
+
+    @property
+    def response(self):
+        return JSONResponse(
+            content={
+                "id": self.id,
+                "message": self.message
+            },
+            status_code=self.code
+        )
+
+
+class NotFound(EntityError):
+    """The entity does not exist"""
+    message = "The entity does not exist"
+    code = statuscode.HTTP_404_NOT_FOUND
+
+
+class PersonNotFound(NotFound):
+    """The Person does not exist"""
+    message = "The person does not exist"

people_api/middlewares.py

@@ -0,0 +1,25 @@
+"""MIDDLEWARES
+Functions that run as something gets processed
+"""
+
+# # Installed # #
+from fastapi import Request
+
+# # Package # #
+from .exceptions import *
+
+__all__ = ("request_handler",)
+
+
+async def request_handler(request: Request, call_next):
+    """Middleware used to process each request on FastAPI, to provide error handling (convert exceptions to responses).
+    TODO: add logging and individual request traceability
+    """
+    try:
+        return await call_next(request)
+
+    except Exception as ex:
+        if isinstance(ex, EntityError):
+            return ex.response
+
+        raise ex

people_api/models/__init__.py

@@ -0,0 +1,4 @@
+from .person_update import *
+from .person_create import *
+from .person_read import *
+from .person_address import *

people_api/models/common.py

@@ -0,0 +1,28 @@
+"""MODELS - COMMON
+Common variables and base classes for the models
+"""
+
+# # Installed # #
+import pydantic
+
+__all__ = ("BaseModel",)
+
+
+class BaseModel(pydantic.BaseModel):
+    """All data models inherit from this class"""
+
+    @pydantic.root_validator(pre=True)
+    def _min_properties(cls, data):
+        """At least one property is required"""
+        if not data:
+            raise ValueError("At least one property is required")
+        return data
+
+    def dict(self, include_nulls=False, **kwargs):
+        """Override the super dict method by removing null keys from the dict, unless include_nulls=True"""
+        kwargs["exclude_none"] = not include_nulls
+        return super().dict(**kwargs)
+
+    class Config:
+        extra = pydantic.Extra.forbid  # forbid sending additional fields/properties
+        anystr_strip_whitespace = True  # strip whitespaces from strings