{"schemaVersion":"1.0","type":"TechArticle","types":["Article","TechArticle"],"slug":"mini-project-2-a-rest-api-with-tests-docker-and-ci-wcv70","url":"https://zyvop.com/mini-project-2-a-rest-api-with-tests-docker-and-ci-wcv70","title":"Mini Project 2: A REST API with Tests, Docker, and CI","subtitle":"Build a REST API that stores and renders prompt templates, with validation, API-key auth, thorough tests, a Docker image, and a CI pipeline that checks every pull request.","tldr":"Turn your Python skills into a service other programs can call. This project builds a prompt-template API with safe rendering, tests for every error path, a smoke test, a Docker image, and GitHub Actions CI.","keywords":["Docker","Flask","AI Engineer","REST API","CI/CD","AI","Zero to Top AI Engineer (2026): Full Series Plan"],"entities":["Pradeep Kumar","Docker","Flask","AI Engineer","REST API","CI/CD","AI","Zero to Top AI Engineer (2026): Full Series Plan","ZyVOP"],"keyTakeaways":["Last project you built a tool for yourself.","This time you'll build a service that other programs talk to: a small REST API that stores and renders prompt templates, with real tests, a Docker image, and a pipeline that checks every change.","One change from what I promised earlier: I said this project would use FastAPI."],"headings":["What we're building","A session with the finished API","The design","Step 0: set up","Step 1: the core, with no web in sight","Step 2: the store","Step 3: the web layer","Step 4: run it","Step 5: the tests","Step 6: a smoke test for the running service","Step 7: Docker","Step 8: continuous integration","A clean history","The FastAPI version","Where to take it next","A definition of done","What to take away"],"outboundLinks":[],"contentText":"Last project you built a tool for yourself. This time you'll build a service that other programs talk to: a small REST API that stores and renders prompt templates, with real tests, a Docker image, and a pipeline that checks every change. One change from what I promised earlier: I said this project would use FastAPI. I built it with Flask instead, because FastAPI and Pydantic couldn't be installed in my test environment, and I wanted every line run for real. The design doesn't depend on the framework, and near the end there's a short FastAPI version, clearly marked as not run. Here's what I verified and what I didn't. The API, its 44 tests (run with a small stand-in for pytest, as in Post 13), a real server session with curl, and the smoke-test script all ran. The Docker image, gunicorn, and the GitHub Actions workflow did not, because I have no Docker or GitHub here. The workflow file parses as valid YAML, and that's all I can promise about it. What we're building Teams that work with language models end up with a pile of prompts. A prompt template with named blanks, like Summarize {text} for a {audience}., is worth storing, naming, and reusing. So our API stores templates, and fills in the blanks on request. Method and path What it does Success code GET /health Liveness check, no key needed 200 POST /prompts Create a prompt 201 GET /prompts List prompts (?tag=, ?limit=, ?offset=) 200 GET /prompts/{name} Fetch one prompt 200 PUT /prompts/{name} Replace its template and tags 200 DELETE /prompts/{name} Delete it 204 POST /prompts/{name}/render Fill in the blanks with variables 200 The status codes come from Post 20, and each failure has a job: Code When 400 The body isn't valid JSON 401 The API key is missing or wrong 404 No such prompt (or no such route) 409 A prompt with that name already exists 413 The request body is too large 422 The JSON is fine, but the content is invalid (bad name, missing variables) 500 Our bug. It's logged, and the client gets a polite JSON error Every error uses the same JSON shape, so clients only need to learn it once: {\"error\": {\"code\": \"missing_variables\", \"message\": \"some variables are missing\", \"missing\": [\"audience\"]}}A session with the finished API I started the server with an API key set, then used curl (Post 23). Each snippet below is real output. Flask prints JSON with its keys in alphabetical order, so the fields look shuffled. Without the key: $ curl -i http://localhost:8765/prompts HTTP/1.1 401 UNAUTHORIZED WWW-Authenticate: Bearer {\"error\":{\"code\":\"unauthorized\",\"message\":\"missing or invalid API key\"}}Creating a prompt with the key (-H \"Authorization: Bearer secret\"): $ curl -i -X POST -H \"$AUTH\" -H \"Content-Type: application/json\" \\ -d '{\"name\": \"summarize\", \"template\": \"Summarize {text} for a {audience}.\", \"tags\": [\"Writing\"]}' \\ http://localhost:8765/prompts HTTP/1.1 201 CREATED Location: /prompts/summarize {\"created_at\":\"2026-11-18T16:16:15+00:00\",\"name\":\"summarize\",\"tags\":[\"writing\"],\"template\":\"Summarize {text} for a {audience}.\",\"updated_at\":\"2026-11-18T16:16:15+00:00\"}Notice the Location header, which tells the client where the new prompt lives, and that the tag Writing came back as writing. Creating the same name again gives a 409: {\"error\":{\"code\":\"conflict\",\"message\":\"a prompt named 'summarize' already exists\"}}A bad request reports every problem at once, not just the first: {\"error\":{\"code\":\"validation_failed\",\"fields\":{\"name\":\"must be 1 to 64 characters: lowercase letters, digits, '-' or '_', starting with a letter or digit\",\"template\":\"unsupported placeholder {user.name}: use plain names like {topic}\"},\"message\":\"the prompt is not valid\"}}Now the point of it all, rendering. With both variables supplied, then with one forgotten: $ curl -X POST ... -d '{\"variables\": {\"text\": \"this article\", \"audience\": \"beginner\"}}' .../prompts/summarize/render {\"name\":\"summarize\",\"text\":\"Summarize this article for a beginner.\"} $ curl -X POST ... -d '{\"variables\": {\"text\": \"this article\"}}' .../prompts/summarize/render {\"error\":{\"code\":\"missing_variables\",\"message\":\"some variables are missing\",\"missing\":[\"audience\"]}}Filtering by tag, deleting (a 204 with no body), and fetching the deleted prompt (a 404 in the same JSON shape) all worked too. The design Three layers, each with one job, like in the last project: promptapi/ ├── pyproject.toml ├── requirements.txt ├── Dockerfile ├── .dockerignore ├── .github/workflows/ci.yml ├── scripts/smoke_test.sh ├── src/promptapi/ │ ├── prompts.py # validation and template rendering (pure: no web, no database) │ ├── store.py # saving prompts in SQLite (no web) │ └── app.py # routes, auth, error responses (the only part that knows about HTTP) └── tests/test_promptapi.pyThe app is built by a function, create_app(db_path, api_key), instead of being a global object. That's the dependency injection from Post 24: a test passes in a temporary database and a known key, and the real server passes in values from environment variables. Nothing is hard-wired. A few decisions are worth explaining before the code. Templates are checked, not trusted. The obvious way to fill in a template is Python's str.format. But a template is user input, and str.format can do far more than substitute names. Look: &gt;&gt;&gt; \"Hello {person.__class__}\".format(person=\"Asha\") \"Hello &lt;class 'str'&gt;\" &gt;&gt;&gt; class Config: ... secret_key = \"do-not-leak\" &gt;&gt;&gt; class Holder: ... def __init__(self): self.config = Config() &gt;&gt;&gt; \"Key is {h.config.secret_key}\".format(h=Holder()) 'Key is do-not-leak'A placeholder can reach into attributes of any object it's given, and in a real program that can mean secrets. So we accept only plain names. {topic} is fine, while {user.name}, {items[0]}, {0}, {}, {x!r}, and {x:&gt;5} are all rejected when the prompt is created, so a bad template never gets stored. (Escaped braces, like {{this}}, are fine and render as literal braces.) The API key is compared safely. We use hmac.compare_digest, which takes the same time whether the first character or the last one is wrong. An ordinary == can leak, through tiny timing differences, how much of a guess was right. The key itself comes from an environment variable (Post 12), never from the code. Limits everywhere. Request bodies are capped at 64 KB, names are 64 characters at most, templates 10,000, and a prompt can have at most 10 tags. Services without limits eventually get hurt by them. Errors are always JSON, even for routes that don't exist and for our own crashes, so a client never has to parse an HTML error page. Step 0: set up mkdir promptapi &amp;&amp; cd promptapi git init -b main python -m venv .venv source .venv/bin/activate mkdir -p src/promptapi tests scriptspyproject.toml: [project] name = \"promptapi\" version = \"0.1.0\" description = \"A small REST API for storing and rendering prompt templates\" readme = \"README.md\" requires-python = \"&gt;=3.11\" dependencies = [\"flask&gt;=3.0\", \"gunicorn&gt;=22.0\"] [project.optional-dependencies] dev = [\"pytest&gt;=8.0\"] [project.scripts] promptapi = \"promptapi.app:main\" [build-system] requires = [\"setuptools&gt;=68\"] build-backend = \"setuptools.build_meta\" [tool.pytest.ini_options] testpaths = [\"tests\"]Flask is the web framework, and gunicorn is the production server we'll use in the container. [project.scripts] creates a promptapi command that starts the development server. Add a .gitignore: .venv/ __pycache__/ *.egg-info/ .pytest_cache/ *.db .env(*.db and .env keep your data and secrets out of Git, Post 22.) Add a one-line README.md and a src/promptapi/__init__.py containing __version__ = \"0.1.0\", and commit the skeleton. Step 1: the core, with no web in sight src/promptapi/prompts.py holds everything about what makes a valid prompt, and how to fill one in: import re import string NAME_PATTERN = re.compile(r\"^[a-z0-9][a-z0-9_-]{0,63}$\") FIELD_NAME = re.compile(r\"^[A-Za-z_][A-Za-z0-9_]*$\") MAX_TEMPLATE_LENGTH = 10_000 MAX_TAGS = 10 MAX_TAG_LENGTH = 32 class ValidationError(Exception): def __init__(self, fields: dict[str, str]): super().__init__(\"invalid prompt\") self.fields = fields class MissingVariables(Exception): def __init__(self, missing: list[str]): super().__init__(\"missing variables: \" + \", \".join(missing)) self.missing = missing def placeholders(template: str) -&gt; list[str]: \"\"\"The {names} in a template, in order, without repeats. Only plain names are allowed. Anything fancier, like {user.name}, {0}, {x!r} or {x:&gt;5}, raises ValueError. \"\"\" names: list[str] = [] try: parsed = list(string.Formatter().parse(template)) except ValueError as error: # for example a lone '{' or '}' raise ValueError(str(error)) from error for _, field, spec, conversion in parsed: if field is None: continue if not FIELD_NAME.match(field) or spec or conversion: written = field + (f\"!{conversion}\" if conversion else \"\") + (f\":{spec}\" if spec else \"\") raise ValueError(f\"unsupported placeholder {{{written}}}: use plain names like {{topic}}\") if field not in names: names.append(field) return names def render(template: str, variables: dict) -&gt; str: needed = placeholders(template) missing = [name for name in needed if name not in variables] if missing: raise MissingVariables(missing) return template.format(**{name: str(variables[name]) for name in needed}) def validate_prompt(data: object, name: str | None = None) -&gt; dict: \"\"\"Check a request body. Returns clean values, or raises ValidationError listing every problem. Pass `name` when it comes from the URL instead of the body. \"\"\" if not isinstance(data, dict): raise ValidationError({\"body\": \"must be a JSON object\"}) problems: dict[str, str] = {} clean: dict = {} if name is None: raw_name = data.get(\"name\") if not isinstance(raw_name, str) or not NAME_PATTERN.match(raw_name): problems[\"name\"] = \"must be 1 to 64 characters: lowercase letters, digits, '-' or '_', starting with a letter or digit\" else: clean[\"name\"] = raw_name template = data.get(\"template\") if not isinstance(template, str) or not template.strip(): problems[\"template\"] = \"must be a non-empty string\" elif len(template) &gt; MAX_TEMPLATE_LENGTH: problems[\"template\"] = f\"must be at most {MAX_TEMPLATE_LENGTH} characters\" else: try: placeholders(template) except ValueError as error: problems[\"template\"] = str(error) else: clean[\"template\"] = template tags = data.get(\"tags\", []) if ( not isinstance(tags, list) or len(tags) &gt; MAX_TAGS or not all(isinstance(t, str) and 0 &lt; len(t.strip()) &lt;= MAX_TAG_LENGTH for t in tags) ): problems[\"tags\"] = f\"must be a list of at most {MAX_TAGS} non-empty strings of up to {MAX_TAG_LENGTH} characters\" else: clean[\"tags\"] = list(dict.fromkeys(t.strip().lower() for t in tags)) if problems: raise ValidationError(problems) return cleanThese are the pieces to understand: Two small exceptions carry information out of the core. ValidationError holds a dictionary of field problems, and MissingVariables holds the names that are missing. The core knows nothing about HTTP status codes. The web layer decides that a ValidationError becomes a 422. placeholders uses string.Formatter().parse, Python's own template parser, to find the names. For each one it checks the name is a plain identifier with no format spec and no conversion. A lone { or } makes the parser itself raise, and we pass that along as a ValueError. render checks for missing names first, then calls format with only the validated names and plain strings. Extra variables are ignored, and non-string values like 29 are converted with str. validate_prompt collects problems instead of stopping at the first. The client fixes everything in one round trip. It also cleans the tags: trimmed, lowercased, de-duplicated with dict.fromkeys, which keeps the order. name= lets the URL supply the name for PUT, where the name isn't in the body. Step 2: the store src/promptapi/store.py saves prompts in SQLite (Post 21): import json import sqlite3 from contextlib import closing from datetime import datetime, timezone SCHEMA = \"\"\" CREATE TABLE IF NOT EXISTS prompts ( name TEXT PRIMARY KEY, template TEXT NOT NULL, tags TEXT NOT NULL DEFAULT '[]', created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); \"\"\" class DuplicateName(Exception): pass def utc_now() -&gt; str: return datetime.now(timezone.utc).isoformat(timespec=\"seconds\") def row_to_dict(row: sqlite3.Row) -&gt; dict: return { \"name\": row[\"name\"], \"template\": row[\"template\"], \"tags\": json.loads(row[\"tags\"]), \"created_at\": row[\"created_at\"], \"updated_at\": row[\"updated_at\"], } class PromptStore: def __init__(self, path: str): self.path = path with closing(self._connect()) as conn, conn: conn.executescript(SCHEMA) def _connect(self) -&gt; sqlite3.Connection: conn = sqlite3.connect(self.path) conn.row_factory = sqlite3.Row return conn def create(self, name: str, template: str, tags: list[str]) -&gt; dict: now = utc_now() try: with closing(self._connect()) as conn, conn: conn.execute( \"INSERT INTO prompts (name, template, tags, created_at, updated_at) VALUES (?, ?, ?, ?, ?)\", (name, template, json.dumps(tags), now, now), ) except sqlite3.IntegrityError as error: raise DuplicateName(name) from error return self.get(name) def get(self, name: str) -&gt; dict | None: with closing(self._connect()) as conn: row = conn.execute(\"SELECT * FROM prompts WHERE name = ?\", (name,)).fetchone() return row_to_dict(row) if row else None def list_prompts(self, tag: str | None = None, limit: int = 20, offset: int = 0) -&gt; tuple[list[dict], int]: where = \"\" params: list = [] if tag: where = \"WHERE EXISTS (SELECT 1 FROM json_each(prompts.tags) WHERE value = ?)\" params.append(tag.lower()) with closing(self._connect()) as conn: total = conn.execute(f\"SELECT COUNT(*) FROM prompts {where}\", params).fetchone()[0] rows = conn.execute( f\"SELECT * FROM prompts {where} ORDER BY name LIMIT ? OFFSET ?\", [*params, limit, offset] ).fetchall() return [row_to_dict(row) for row in rows], total def update(self, name: str, template: str, tags: list[str]) -&gt; dict | None: with closing(self._connect()) as conn, conn: cursor = conn.execute( \"UPDATE prompts SET template = ?, tags = ?, updated_at = ? WHERE name = ?\", (template, json.dumps(tags), utc_now(), name), ) return self.get(name) if cursor.rowcount else None def delete(self, name: str) -&gt; bool: with closing(self._connect()) as conn, conn: cursor = conn.execute(\"DELETE FROM prompts WHERE name = ?\", (name,)) return cursor.rowcount == 1A few details: A new connection for every call, closed afterward with closing. SQLite connections are cheap, and this avoids sharing one between threads. And with conn: makes each write a transaction that commits on success and rolls back on an error. The database enforces uniqueness. name is the primary key, so a duplicate insert raises sqlite3.IntegrityError, which we translate into our own DuplicateName. Checking \"does it exist?\" first and inserting second would have a race, with two requests both passing the check. Every query uses ? placeholders. No values are ever pasted into SQL. Tags are stored as JSON text, and the tag filter uses SQLite's json_each to look inside it. Timestamps are UTC ISO strings. One naming slip is worth confessing. My first version called the listing method list. The file crashed on import with TypeError: 'function' object is not subscriptable, because inside the class, list now meant my method, and a later annotation list[str] tried to subscript it. The method is list_prompts now. Don't name things after built-ins. Step 3: the web layer src/promptapi/app.py ties it together: import hmac import os from flask import Flask, jsonify, request from werkzeug.exceptions import HTTPException from promptapi.prompts import MissingVariables, ValidationError, render, validate_prompt from promptapi.store import DuplicateName, PromptStore MAX_BODY_BYTES = 64 * 1024 def create_app(db_path: str, api_key: str | None = None) -&gt; Flask: app = Flask(__name__) app.config[\"MAX_CONTENT_LENGTH\"] = MAX_BODY_BYTES store = PromptStore(db_path) def error(status: int, code: str, message: str, **details): response = jsonify({\"error\": {\"code\": code, \"message\": message, **details}}) response.status_code = status return response @app.before_request def require_api_key(): if api_key is None or request.endpoint == \"health\": return None scheme, _, token = request.headers.get(\"Authorization\", \"\").partition(\" \") if scheme.lower() == \"bearer\" and hmac.compare_digest(token.encode(), api_key.encode()): return None response = error(401, \"unauthorized\", \"missing or invalid API key\") response.headers[\"WWW-Authenticate\"] = \"Bearer\" return response @app.errorhandler(HTTPException) def http_error(exc: HTTPException): return error(exc.code or 500, exc.name.lower().replace(\" \", \"_\"), exc.description or exc.name) @app.errorhandler(Exception) def unexpected_error(exc: Exception): app.logger.exception(\"unhandled error\") return error(500, \"internal_error\", \"something went wrong on our side\") @app.get(\"/health\") def health(): return jsonify(status=\"ok\") @app.post(\"/prompts\") def create_prompt(): data = request.get_json(silent=True) if data is None: return error(400, \"bad_request\", \"the request body must be valid JSON\") try: clean = validate_prompt(data) except ValidationError as problem: return error(422, \"validation_failed\", \"the prompt is not valid\", fields=problem.fields) try: prompt = store.create(clean[\"name\"], clean[\"template\"], clean[\"tags\"]) except DuplicateName: return error(409, \"conflict\", f\"a prompt named '{clean['name']}' already exists\") response = jsonify(prompt) response.status_code = 201 response.headers[\"Location\"] = f\"/prompts/{prompt['name']}\" return response @app.get(\"/prompts\") def list_prompts(): try: limit = int(request.args.get(\"limit\", 20)) offset = int(request.args.get(\"offset\", 0)) except ValueError: return error(422, \"validation_failed\", \"limit and offset must be whole numbers\") if not 1 &lt;= limit &lt;= 100 or offset &lt; 0: return error(422, \"validation_failed\", \"limit must be 1 to 100, and offset must not be negative\") items, total = store.list_prompts(tag=request.args.get(\"tag\"), limit=limit, offset=offset) return jsonify(items=items, total=total, limit=limit, offset=offset) @app.get(\"/prompts/&lt;name&gt;\") def get_prompt(name: str): prompt = store.get(name) if prompt is None: return error(404, \"not_found\", f\"no prompt named '{name}'\") return jsonify(prompt) @app.put(\"/prompts/&lt;name&gt;\") def replace_prompt(name: str): data = request.get_json(silent=True) if data is None: return error(400, \"bad_request\", \"the request body must be valid JSON\") try: clean = validate_prompt(data, name=name) except ValidationError as problem: return error(422, \"validation_failed\", \"the prompt is not valid\", fields=problem.fields) prompt = store.update(name, clean[\"template\"], clean[\"tags\"]) if prompt is None: return error(404, \"not_found\", f\"no prompt named '{name}'\") return jsonify(prompt) @app.delete(\"/prompts/&lt;name&gt;\") def delete_prompt(name: str): if not store.delete(name): return error(404, \"not_found\", f\"no prompt named '{name}'\") return \"\", 204 @app.post(\"/prompts/&lt;name&gt;/render\") def render_prompt(name: str): prompt = store.get(name) if prompt is None: return error(404, \"not_found\", f\"no prompt named '{name}'\") data = request.get_json(silent=True) variables = data.get(\"variables\", {}) if isinstance(data, dict) else None if not isinstance(variables, dict): return error(422, \"validation_failed\", \"send a JSON object with a 'variables' object inside it\") try: text = render(prompt[\"template\"], variables) except MissingVariables as problem: return error(422, \"missing_variables\", \"some variables are missing\", missing=problem.missing) return jsonify(name=name, text=text) return app def create_app_from_env() -&gt; Flask: return create_app(os.environ.get(\"PROMPT_DB\", \"prompts.db\"), os.environ.get(\"PROMPT_API_KEY\") or None) def main() -&gt; None: \"\"\"Run the development server. For real deployments, use gunicorn (see the Dockerfile).\"\"\" app = create_app_from_env() app.run(host=os.environ.get(\"HOST\", \"127.0.0.1\"), port=int(os.environ.get(\"PORT\", \"8000\")))Reading it top to bottom: before_request runs before every route. It skips /health, and if a key is configured, it requires Authorization: Bearer &lt;key&gt;, answering 401 with a WWW-Authenticate header otherwise. Passing api_key=None turns authentication off, which is handy for local use. The two error handlers make errors JSON. One converts Flask's own HTTP errors (404, 405, 413), and one catches anything unexpected, logs the traceback for us, and tells the client only that something went wrong. We never send a stack trace to a client. request.get_json(silent=True) returns None instead of raising when the body isn't valid JSON, so we can answer with our own 400. Creating returns 201 with a Location header, deleting returns 204 with no body, and both are conventions that clients rely on. List parameters are validated. limit must be 1 to 100, so nobody can ask for a million rows. main() runs Flask's development server, which is fine on your laptop and not for real traffic. The server prints a warning saying exactly that. In the container we'll run gunicorn instead, through create_app_from_env. Step 4: run it pip install -e \".[dev]\" PROMPT_API_KEY=secret promptapiThe server reads its settings from environment variables: PROMPT_DB (where the SQLite file lives, default prompts.db), PROMPT_API_KEY (leave it unset for an open API), HOST (default 127.0.0.1), and PORT (default 8000). Try the curl commands from the session above. Then stop the server, start it again, and fetch a prompt you created before. It's still there, because the data lives in the database file and not in the process. I checked exactly that: I created a prompt, restarted the server on the same file, and got it back. Step 5: the tests Create tests/test_promptapi.py. It has two layers, just like the code. The first group tests the core with plain function calls. The second tests the web layer, using Flask's built-in test client, which sends requests straight into the app with no real server or network: import pytest from promptapi.app import create_app from promptapi.prompts import MissingVariables, ValidationError, placeholders, render, validate_prompt API_KEY = \"test-secret\" AUTH = {\"Authorization\": f\"Bearer {API_KEY}\"} @pytest.fixture def db_path(tmp_path): return str(tmp_path / \"prompts.db\") @pytest.fixture def client(db_path): return create_app(db_path, api_key=API_KEY).test_client() def create(client, name=\"summarize\", template=\"Summarize {text} for a {audience}.\", tags=None): payload = {\"name\": name, \"template\": template} if tags is not None: payload[\"tags\"] = tags return client.post(\"/prompts\", json=payload, headers=AUTH) # ---- the core: templates and validation (no web server involved) ---- @pytest.mark.parametrize(\"template, expected\", [ (\"Hello {name}\", [\"name\"]), (\"{a} and {b} and {a}\", [\"a\", \"b\"]), (\"no placeholders at all\", []), (\"{{literal braces}}\", []), ]) def test_placeholders(template, expected): assert placeholders(template) == expected @pytest.mark.parametrize(\"template\", [ \"{0}\", \"{}\", \"{user.name}\", \"{items[0]}\", \"{x!r}\", \"{x:&gt;5}\", \"a } b\", \"a { b\", ]) def test_anything_fancier_than_a_plain_name_is_rejected(template): with pytest.raises(ValueError): placeholders(template) def test_render_fills_in_variables_and_ignores_extras(): text = render(\"Hi {name}, you are {age}.\", {\"name\": \"Asha\", \"age\": 29, \"unused\": True}) assert text == \"Hi Asha, you are 29.\" def test_render_keeps_escaped_braces(): assert render(\"Use {{braces}} for {thing}\", {\"thing\": \"JSON\"}) == \"Use {braces} for JSON\" def test_render_reports_every_missing_variable(): with pytest.raises(MissingVariables) as excinfo: render(\"{a} {b} {c}\", {\"b\": 1}) assert excinfo.value.missing == [\"a\", \"c\"] def test_validation_reports_all_problems_at_once(): with pytest.raises(ValidationError) as excinfo: validate_prompt({\"name\": \"Bad Name\", \"template\": \"\", \"tags\": \"nope\"}) assert set(excinfo.value.fields) == {\"name\", \"template\", \"tags\"} def test_validation_cleans_tags_and_can_take_the_name_from_the_url(): clean = validate_prompt({\"template\": \"x {y}\", \"tags\": [\" Writing \", \"writing\", \"Summary\"]}, name=\"from-url\") assert clean == {\"template\": \"x {y}\", \"tags\": [\"writing\", \"summary\"]} # ---- authentication ---- def test_health_needs_no_key(client): assert client.get(\"/health\").get_json() == {\"status\": \"ok\"} @pytest.mark.parametrize(\"headers\", [{}, {\"Authorization\": \"Bearer wrong\"}, {\"Authorization\": \"Basic abc\"}, {\"Authorization\": API_KEY}]) def test_other_endpoints_reject_a_missing_or_wrong_key(client, headers): response = client.get(\"/prompts\", headers=headers) assert response.status_code == 401 assert response.headers[\"WWW-Authenticate\"] == \"Bearer\" assert response.get_json()[\"error\"][\"code\"] == \"unauthorized\" def test_without_a_configured_key_the_api_is_open(db_path): open_client = create_app(db_path, api_key=None).test_client() assert open_client.get(\"/prompts\").status_code == 200 # ---- creating and reading prompts ---- def test_create_returns_201_with_a_location_and_the_stored_prompt(client): response = create(client, tags=[\"Writing\"]) body = response.get_json() assert response.status_code == 201 assert response.headers[\"Location\"] == \"/prompts/summarize\" assert body[\"name\"] == \"summarize\" assert body[\"tags\"] == [\"writing\"] assert body[\"created_at\"] == body[\"updated_at\"] def test_a_duplicate_name_is_a_conflict(client): create(client) response = create(client) assert response.status_code == 409 assert response.get_json()[\"error\"][\"code\"] == \"conflict\" def test_an_invalid_prompt_is_rejected_with_field_messages(client): response = client.post(\"/prompts\", json={\"name\": \"Bad Name!\", \"template\": \"\"}, headers=AUTH) error = response.get_json()[\"error\"] assert response.status_code == 422 assert error[\"code\"] == \"validation_failed\" assert set(error[\"fields\"]) == {\"name\", \"template\"} def test_a_template_that_could_reach_into_objects_is_rejected(client): response = create(client, template=\"Hello {user.__class__}\") assert response.status_code == 422 assert \"unsupported placeholder\" in response.get_json()[\"error\"][\"fields\"][\"template\"] def test_malformed_json_is_a_400(client): response = client.post(\"/prompts\", data=\"not json\", content_type=\"application/json\", headers=AUTH) assert response.status_code == 400 def test_an_oversized_body_is_rejected_as_json(client): response = client.post(\"/prompts\", data=\"x\" * 70_000, content_type=\"application/json\", headers=AUTH) assert response.status_code == 413 assert response.get_json()[\"error\"][\"code\"] == \"request_entity_too_large\" def test_get_returns_the_prompt_or_a_json_404(client): create(client) assert client.get(\"/prompts/summarize\", headers=AUTH).get_json()[\"template\"].startswith(\"Summarize\") missing = client.get(\"/prompts/nope\", headers=AUTH) assert missing.status_code == 404 assert missing.get_json()[\"error\"][\"code\"] == \"not_found\" def test_an_unknown_route_is_also_json(client): response = client.get(\"/nothing-here\", headers=AUTH) assert response.status_code == 404 assert response.get_json()[\"error\"][\"code\"] == \"not_found\" # ---- listing ---- def test_list_is_sorted_filterable_and_paged(client): create(client, name=\"b-prompt\", template=\"b {x}\", tags=[\"writing\"]) create(client, name=\"a-prompt\", template=\"a {x}\", tags=[\"writing\", \"code\"]) create(client, name=\"c-prompt\", template=\"c {x}\", tags=[\"code\"]) everything = client.get(\"/prompts\", headers=AUTH).get_json() assert [p[\"name\"] for p in everything[\"items\"]] == [\"a-prompt\", \"b-prompt\", \"c-prompt\"] assert everything[\"total\"] == 3 by_tag = client.get(\"/prompts?tag=Code\", headers=AUTH).get_json() assert [p[\"name\"] for p in by_tag[\"items\"]] == [\"a-prompt\", \"c-prompt\"] page = client.get(\"/prompts?limit=1&amp;offset=1\", headers=AUTH).get_json() assert [p[\"name\"] for p in page[\"items\"]] == [\"b-prompt\"] assert page[\"total\"] == 3 @pytest.mark.parametrize(\"query\", [\"limit=0\", \"limit=101\", \"limit=abc\", \"offset=-1\"]) def test_bad_paging_values_are_rejected(client, query): assert client.get(f\"/prompts?{query}\", headers=AUTH).status_code == 422 # ---- updating and deleting ---- def test_put_replaces_the_template_and_tags(client): create(client, tags=[\"old\"]) response = client.put(\"/prompts/summarize\", json={\"template\": \"New {thing}\", \"tags\": [\"new\"]}, headers=AUTH) body = response.get_json() assert response.status_code == 200 assert (body[\"template\"], body[\"tags\"]) == (\"New {thing}\", [\"new\"]) assert client.put(\"/prompts/nope\", json={\"template\": \"x\"}, headers=AUTH).status_code == 404 def test_delete_returns_204_and_then_404(client): create(client) assert client.delete(\"/prompts/summarize\", headers=AUTH).status_code == 204 assert client.delete(\"/prompts/summarize\", headers=AUTH).status_code == 404 assert client.get(\"/prompts/summarize\", headers=AUTH).status_code == 404 # ---- rendering ---- def test_render_fills_in_the_template(client): create(client) response = client.post(\"/prompts/summarize/render\", json={\"variables\": {\"text\": \"this article\", \"audience\": \"beginner\"}}, headers=AUTH) assert response.status_code == 200 assert response.get_json()[\"text\"] == \"Summarize this article for a beginner.\" def test_render_lists_missing_variables(client): create(client) response = client.post(\"/prompts/summarize/render\", json={\"variables\": {\"text\": \"x\"}}, headers=AUTH) error = response.get_json()[\"error\"] assert response.status_code == 422 assert (error[\"code\"], error[\"missing\"]) == (\"missing_variables\", [\"audience\"]) @pytest.mark.parametrize(\"body\", [{\"variables\": \"text\"}, [\"not\", \"an\", \"object\"]]) def test_render_needs_a_variables_object(client, body): create(client) assert client.post(\"/prompts/summarize/render\", json=body, headers=AUTH).status_code == 422 def test_render_of_an_unknown_prompt_is_a_404(client): assert client.post(\"/prompts/nope/render\", json={\"variables\": {}}, headers=AUTH).status_code == 404 # ---- persistence ---- def test_data_survives_a_restart(db_path): first = create_app(db_path, api_key=API_KEY).test_client() create(first) second = create_app(db_path, api_key=API_KEY).test_client() assert second.get(\"/prompts/summarize\", headers=AUTH).status_code == 200Some patterns here are worth noting: Fixtures build a fresh app for every test, with a database file in a temporary folder and a known key. Tests can't affect each other. parametrize covers the awkward cases cheaply. Eight fancy templates that must be rejected, four wrong ways to send the key, four bad paging values. Each is one line. Every error path has a test: 400, 401, 404, 409, 413, and 422. The success paths alone would only prove the easy half. The restart test creates two separate apps on the same database file, to prove data isn't held in memory. There are 27 test functions, which expand to 44 cases with parametrize, and all 44 passed. Then came the check from Post 13, to make sure the tests can fail. I broke the code six different ways, one at a time: Deliberate bug Tests that failed Accept any bearer token (and changed to or) 1 DELETE answers 200 instead of 204 1 Allow fancy placeholders like {user.name} 7 Tag filter forgets to lowercase 1 No request size limit 1 render ignores missing variables 2 Every bug was caught, and after restoring the code all 44 passed again. Note what the third row says: the security rule isn't just documented. Seven separate tests would turn red if someone weakened it. Step 6: a smoke test for the running service Unit tests prove the pieces work. A smoke test proves the deployed thing works: that the server started, that it's reachable, and that the main path works end to end. It's a shell script (Post 23) that takes the address as an argument, so it can test your laptop, a container, or a server in the cloud. scripts/smoke_test.sh: #!/usr/bin/env bash set -euo pipefail BASE=\"${1:-http://localhost:8000}\" KEY=\"${PROMPT_API_KEY:-}\" AUTH=\"Authorization: Bearer ${KEY}\" echo \"Checking $BASE ...\" for attempt in 1 2 3 4 5 6 7 8 9 10; do if curl -fsS \"$BASE/health\" &gt; /dev/null 2&gt;&amp;1; then break fi echo \"Not ready yet (attempt $attempt), waiting...\" sleep 1 done status=$(curl -s -o /dev/null -w \"%{http_code}\" \"$BASE/health\" || true) if [ \"$status\" -ne 200 ]; then echo \"FAIL: /health returned $status\" &gt;&amp;2 exit 1 fi # start from a clean slate, in case an earlier run left the prompt behind curl -s -o /dev/null -X DELETE -H \"$AUTH\" \"$BASE/prompts/smoke-test\" || true created=$(curl -s -o /dev/null -w \"%{http_code}\" -X POST -H \"$AUTH\" -H \"Content-Type: application/json\" \\ -d '{\"name\": \"smoke-test\", \"template\": \"Explain {topic} to a {audience}.\"}' \"$BASE/prompts\" || true) if [ \"$created\" -ne 201 ]; then echo \"FAIL: creating a prompt returned $created\" &gt;&amp;2 exit 1 fi rendered=$(curl -fsS -X POST -H \"$AUTH\" -H \"Content-Type: application/json\" \\ -d '{\"variables\": {\"topic\": \"generators\", \"audience\": \"beginner\"}}' \"$BASE/prompts/smoke-test/render\") echo \"Rendered: $rendered\" case \"$rendered\" in *\"Explain generators to a beginner.\"*) ;; *) echo \"FAIL: unexpected render output\" &gt;&amp;2; exit 1 ;; esac curl -fsS -o /dev/null -X DELETE -H \"$AUTH\" \"$BASE/prompts/smoke-test\" echo \"OK\"Make it executable with chmod +x scripts/smoke_test.sh. It waits for the server to come up (a fresh container isn't instantly ready), cleans up after any earlier run, creates a prompt, renders it, checks the result, and deletes it. The || true on the curl calls matters under set -e, as we saw in Post 23: it lets our message appear instead of the script dying silently. I ran it three ways: Situation Output Exit code Server not running FAIL: /health returned 000 1 Server running with a key, script without one FAIL: creating a prompt returned 401 1 Server running with a key, script with PROMPT_API_KEY=secret Rendered: {\"name\":\"smoke-test\",\"text\":\"Explain generators to a beginner.\"} then OK 0 The second row is a good example of what a smoke test is for: /health is open, so the server looked healthy, yet the real work was blocked. Only a test that goes through the whole path catches that. Step 7: Docker Everything in this section and the next is from my knowledge and not something I ran, since I had no Docker or GitHub. Check the commands against their documentation as you go. The Dockerfile applies what we learned in Post 23: FROM python:3.12-slim ENV PYTHONUNBUFFERED=1 \\ PROMPT_DB=/data/prompts.db WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY pyproject.toml README.md ./ COPY src ./src RUN pip install --no-cache-dir --no-deps . RUN useradd --create-home appuser &amp;&amp; mkdir /data &amp;&amp; chown appuser /data USER appuser VOLUME /data EXPOSE 8000 HEALTHCHECK --interval=30s --timeout=3s \\ CMD python -c \"import urllib.request; urllib.request.urlopen('http://localhost:8000/health')\" CMD [\"gunicorn\", \"--bind\", \"0.0.0.0:8000\", \"promptapi.app:create_app_from_env()\"]Why it's built this way: Layer caching. requirements.txt is copied and installed before the source code, so editing code doesn't reinstall Flask. The file repeats the dependencies in pyproject.toml, so keep the two in sync. The final pip install --no-deps . installs only our own package. gunicorn, not Flask's development server. It's a production-grade server, and create_app_from_env() is a factory call that builds our app using the environment variables. It listens on 0.0.0.0 so the container is reachable from outside. The database lives in a volume, /data, because a container's own filesystem is thrown away with the container. It runs as a non-root user, and PYTHONUNBUFFERED=1 makes logs appear immediately. HEALTHCHECK lets Docker itself ask /health every 30 seconds. Secrets aren't baked in. The key is passed when the container starts. And .dockerignore, requirements.txt: .git .github .venv __pycache__/ *.egg-info/ .pytest_cache/ *.db .env tests/flask&gt;=3.0 gunicorn&gt;=22.0To build and run it, and then test the container with the same script we used on the laptop: docker build -t promptapi . docker run -d --name api -p 8000:8000 -v prompts:/data -e PROMPT_API_KEY=secret promptapi PROMPT_API_KEY=secret ./scripts/smoke_test.sh http://localhost:8000 docker logs api docker stop api &amp;&amp; docker rm apiBecause the data is in the prompts volume, you should be able to stop and remove the container, start a new one with the same -v prompts:/data, and find your prompts still there. Step 8: continuous integration Continuous integration, or CI, means a server automatically runs your checks on every push and every pull request, so nobody has to remember to. On GitHub, it's a workflow file in .github/workflows/. It's useful to know that CI is nothing magic: it's the commands you've already been typing, written into a file. .github/workflows/ci.yml: name: CI on: push: branches: [main] pull_request: jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: [\"3.11\", \"3.12\"] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - name: Install run: pip install -e \".[dev]\" - name: Run the tests run: pytest docker: runs-on: ubuntu-latest needs: test steps: - uses: actions/checkout@v4 - name: Build the image run: docker build -t promptapi . - name: Start the container run: docker run -d --name api -p 8000:8000 promptapi - name: Smoke test run: ./scripts/smoke_test.sh http://localhost:8000 - name: Show the container logs if something failed if: failure() run: docker logs apiReading it: on says when it runs: on every push to main, and on every pull request. The test job checks out your code, sets up Python, installs the project, and runs pytest. The matrix runs it once for each Python version listed, here 3.11 and 3.12, in parallel, so you find out if you've broken an older version. The docker job builds the image, starts the container, runs our smoke test against it, and prints the container's logs only if: failure(), which is exactly when you'd want them. needs: test means it runs only after the tests pass. Each uses: line borrows a ready-made step from the community. The version tags (@v4, @v5) change over time, so check the current ones. I could check that the file is valid YAML and that it has the structure I intended (two jobs, a two-version matrix, needs: test), but I couldn't run it on GitHub. One gotcha to look out for: the script must be executable in Git. On Linux and macOS, chmod +x before committing is enough, and I confirmed Git recorded it as an executable file. If you work on Windows, run git update-index --chmod=+x scripts/smoke_test.sh, or CI will fail with \"permission denied\". Once it's working, combine it with what you learned in Post 22: turn on branch protection so a pull request can't be merged until the checks are green. Then a red cross next to a commit means \"don't merge this yet\", and nobody has to take your word that the tests pass. A clean history As in the last project, I committed as I built, with messages that say what changed: 9d42b39 Add CI workflow: tests, image build, smoke test cf1b1ad Add Dockerfile for gunicorn 8811cc5 Add smoke test script 6c4ee44 Add tests for the core and every endpoint bc8f445 Add Flask app with CRUD, render, auth, and JSON errors cd3f95b Add SQLite prompt store 18acca0 Add prompt validation and safe template rendering 613e65e Set up project skeletongit status was clean at the end. Push it to GitHub and open a pull request, so the CI workflow runs for the first time. The FastAPI version Since I promised FastAPI earlier, here's how the web layer would look. I did not run this, because FastAPI and Pydantic weren't available to me, so treat it as a sketch and check it against the current documentation. The reassuring part is how much doesn't change. prompts.py and store.py are reused as they are, which is the payoff of keeping them free of any web code. from fastapi import FastAPI, HTTPException from pydantic import BaseModel, Field, field_validator from promptapi.prompts import MissingVariables, placeholders, render from promptapi.store import DuplicateName, PromptStore store = PromptStore(\"prompts.db\") app = FastAPI() class PromptIn(BaseModel): name: str = Field(pattern=r\"^[a-z0-9][a-z0-9_-]{0,63}$\") template: str = Field(min_length=1, max_length=10_000) tags: list[str] = Field(default_factory=list, max_length=10) @field_validator(\"template\") @classmethod def only_plain_placeholders(cls, value: str) -&gt; str: placeholders(value) # raises ValueError for anything fancy, which becomes a 422 return value class RenderIn(BaseModel): variables: dict[str, object] = Field(default_factory=dict) @app.post(\"/prompts\", status_code=201) def create_prompt(prompt: PromptIn): try: return store.create(prompt.name, prompt.template, prompt.tags) except DuplicateName: raise HTTPException(status_code=409, detail=f\"a prompt named '{prompt.name}' already exists\") @app.post(\"/prompts/{name}/render\") def render_prompt(name: str, body: RenderIn): prompt = store.get(name) if prompt is None: raise HTTPException(status_code=404, detail=f\"no prompt named '{name}'\") try: return {\"name\": name, \"text\": render(prompt[\"template\"], body.variables)} except MissingVariables as problem: raise HTTPException(status_code=422, detail={\"missing\": problem.missing})You would run it with uvicorn, a server for FastAPI apps, and FastAPI generates interactive documentation at /docs for free. The differences to expect: Pydantic replaces validate_prompt. Field rules like pattern and max_length are declared on the model, and FastAPI rejects bad input with a 422 automatically (Post 10). The error shape changes. FastAPI's errors look like {\"detail\": ...}, not our {\"error\": {...}}, so tests that check the error format would need updating, unless you add your own exception handlers. Tests use fastapi.testclient.TestClient, which works much like Flask's test client. Async is optional. These handlers are ordinary functions. The async style from Post 14 pays off when handlers wait on a model API. Where to take it next Add version history. Keep every past version of a prompt in a second table, with GET /prompts/{name}/versions, so you can roll back a change that made results worse. Add rate limiting per API key, using the atomic-update idea from Post 21. Move to Postgres (Post 21), and use a connection pool. SQLite is great for one server and light traffic. Add request IDs to the logs, so you can trace one request through the system. Add a /prompts/{name}/run endpoint that renders the template and sends it to a model, once you've built your first LLM app in Post 49. This is where the service becomes useful. Deploy it to a cloud service (Post 71), and point the smoke test at the live address. Support several keys, each with its own name, so you can revoke one without breaking the others. A definition of done Every endpoint has a test for success and for each way it can fail. You've broken the code on purpose at least once, and a test noticed. The smoke test passes against your local server and against the container. No secret appears in the code, the image, or the Git history. The README explains how to run it, which environment variables it reads, and what the API looks like. CI is green on a pull request, and your history reads like a story. What to take away A REST API is a set of nouns (URLs), verbs (methods), and consistent answers (status codes and one JSON error shape). Keep the logic out of the web layer. The core and the store here know nothing about HTTP, so they're easy to test and easy to move to another framework. Treat every input as untrusted, even a template. Plain placeholders only, with limits on sizes and counts, and every problem reported at once. Build the app with a factory function, and pass in its settings. Then tests can use a temporary database and a known key. A smoke test checks the running system end to end, and it catches problems that unit tests can't. A Docker image is the app plus its environment. Cache dependencies, run as a non-root user, mount a volume for data, and pass secrets at run time. CI is your commands in a file, run automatically on every change. Pair it with branch protection and it becomes a gate. Previous: Post 27, Mini Project 1: A Markdown Note Searcher Next in the series: Post 29, Capstone, where we build a small Python library and publish it on PyPI.","contentHash":"sha256:3151462cca1a0def1f83c641537757f40103b32e22312334170fadd895479086","authorName":"Pradeep Kumar","authorUrl":"https://zyvop.com/author/pradeep","authorSameAs":[],"category":"AI","tags":["Docker","Flask","AI Engineer","REST API","CI/CD"],"audience":"Software engineers and developers building applications with AI","tone":"Instructional, practical, code-first","readingTimeMinutes":24,"wordCount":6291,"faqs":null,"primaryTopic":"AI","publishedAt":"2026-11-20T10:29:26.823Z","updatedAt":"2026-11-20T10:29:26.823Z","canonicalUrl":"https://zyvop.com/mini-project-2-a-rest-api-with-tests-docker-and-ci-wcv70"}