READmeDev

READmeDev API

A small FastAPI service used to manage simple todo-style items. The project is intentionally lightweight so a reviewer can clone it, start it locally, and exercise one endpoint in under twenty minutes.

What this project does

The service stores items in memory and exposes a minimal CRUD API for todo records. It is designed to be easy to run locally and easy to inspect with the auto-generated FastAPI docs at /docs.

Prerequisites

Use the following concrete versions or newer:

• Python 3.11.9
• pip 24.0+
• FastAPI 0.115.6
• Uvicorn 0.30.6

The project does not require a database, external cache, or cloud service. It reads configuration from environment variables only when they are set.

Repository layout

• app/main.py – FastAPI application and API routes
• tests/test_api.py – Basic API verification tests
• requirements.txt – Runtime and test dependencies
• .gitignore – Ignored local files

Environment variables

This service has no required environment variables for local startup. All variables are optional and default to safe values.

Variable	Example value	Source	Required?	Used for
HOST	0.0.0.0	shell or .env file	No	Bind address for the Uvicorn server
PORT	8000	shell or .env file	No	Port for the HTTP server

If you do not set HOST or PORT, the service still starts on 0.0.0.0:8000.

Local setup

1. Clone the repository.
2. Change into the project directory.
3. Create a virtual environment:

python -m venv .venv

1. Activate it:

• On macOS/Linux:

source .venv/bin/activate

• On Windows PowerShell:

.\.venv\Scripts\Activate.ps1

1. Install dependencies:

pip install -r requirements.txt

1. Start the server:

uvicorn app.main:app --host 0.0.0.0 --port 8000

You can also start it with environment variables:

set HOST=0.0.0.0
set PORT=8000
python app/main.py

The app is ready when you see a Uvicorn startup log that includes the local URL, usually http://127.0.0.1:8000.

How to call the API

The API uses JSON for requests and responses.

Health check

Request:

curl http://127.0.0.1:8000/health

Example response:

{
  "status": "ok",
  "service": "readmedev-api"
}

Status codes:

• 200 OK – service is running

List all items

Request:

curl http://127.0.0.1:8000/items

Example success response:

[
  {
    "id": 1,
    "title": "Write README",
    "completed": false
  }
]

Status codes:

• 200 OK – list returned successfully

Create an item

Request body:

{
  "title": "Write README",
  "completed": false
}

Request:

curl -X POST http://127.0.0.1:8000/items \
  -H "Content-Type: application/json" \
  -d '{"title":"Write README","completed":false}'

Example success response:

{
  "id": 1,
  "title": "Write README",
  "completed": false
}

Status codes:

• 201 Created – item created
• 422 Unprocessable Entity – invalid payload, such as missing title or wrong field types

Get one item

Request:

curl http://127.0.0.1:8000/items/1

Example success response:

{
  "id": 1,
  "title": "Write README",
  "completed": false
}

Status codes:

• 200 OK – item exists
• 404 Not Found – item ID does not exist

Update an item

Request body (partial update is supported):

{
  "title": "Ship project",
  "completed": true
}

Request:

curl -X PUT http://127.0.0.1:8000/items/1 \
  -H "Content-Type: application/json" \
  -d '{"title":"Ship project","completed":true}'

Example success response:

{
  "id": 1,
  "title": "Ship project",
  "completed": true
}

Status codes:

• 200 OK – update succeeded
• 404 Not Found – item ID does not exist
• 422 Unprocessable Entity – request body is invalid

Delete an item

Request:

curl -X DELETE http://127.0.0.1:8000/items/1

Success response: no body, status 204 No Content.

Status codes:

• 204 No Content – deletion succeeded
• 404 Not Found – item ID does not exist

Data model

Each item is represented as:

{
  "id": 1,
  "title": "Write README",
  "completed": false
}

Field definitions:

• id: integer, unique, auto-incrementing
• title: string, required when creating an item
• completed: boolean, defaults to false

The API keeps items in an in-memory dictionary, so data is lost when the process restarts.

API docs

FastAPI automatically generates interactive docs at:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

How to verify the app works

Run the test suite:

pytest

This project includes a basic smoke test covering health, create/get, and update/delete flows.

Decisions to revisit at 10x traffic

At roughly ten times the current traffic, I would revisit these decisions:

1. Replace the in-memory dictionary with a real database so data survives restarts and supports durable writes.
2. Add authentication and authorization if more than a local developer or a single trusted client needs access.
3. Introduce request validation and idempotency safeguards for retries and duplicate submission scenarios.
4. Add structured logging, metrics, and tracing to understand latency and failures under load.
5. Move from a single process to multiple workers or a queue-based worker model if request concurrency grows.
6. Add pagination and filtering to /items to avoid returning unbounded payloads.

Known limitations

• Data exists only in memory and is lost when the server restarts.
• No database migration or persistence layer is included.
• No authentication or authorization is implemented.
• No pagination, search, or filtering is provided on the list endpoint.
• No rate limiting, caching, or concurrency protections are included.
• The app is intentionally minimal and not production-hardened.

Example success path for a reviewer

From a clean clone, a reviewer can do the following:

python -m venv .venv
source .venv/bin/activate  # or .\.venv\Scripts\Activate.ps1 on Windows
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000
curl -X POST http://127.0.0.1:8000/items -H "Content-Type: application/json" -d '{"title":"Write README","completed":false}'

This returns a 201 Created response with a JSON body containing a new item ID.