diff docs

.env_EXAMPLE

@@ -1,5 +1,3 @@
-# Empty values in this file are optional
-
 BASE_URI="https://api.academyruins.com"
 ADMIN_KEY="super-secret-value"
 
@@ -13,7 +11,7 @@ USE_PUSHOVER=0
 PUSHOVER_APP_TOKEN=
 PUSHOVER_USER_KEY=
 
-# Backblaze configuration for data dumps
+# Backblaze/S3 configuration for data dumps
 BACKUP_KEY_ID=
 BACKUP_APP_KEY=
 BACKUP_ENDPOINT=

README.md

@@ -28,7 +28,7 @@ or
 The API server will start on port 8000 by default.
 
 ### Docker
-There's a prepared `Dockerfile` and `docker-compose.yml` file you can inspect and use to run the API fully contained in Docker. Note that if you're running Postgres in a container and want to use `psql` from the host machine, you have to map port 5432 to the host and specify a `--hostname=localhost` flag in order to connect successfully.
+dThere's a prepared `Dockerfile` and `docker-compose.yml` file you can inspect and use to run the API fully contained in a Docker container. Note that if you're running Postgres in a container and want to use `psql` from the host machine, you have to map port 5432 to the host and specify the `--hostname=localhost` flag in any `psql` command in order to connect successfully.
 
 ## Documentation
 The full API docs are available at https://api.academyruins.com/docs

app/routers/diff.py

@@ -1,12 +1,25 @@
+from typing import Union
+
 from fastapi import APIRouter, Response, Path
 from fastapi.responses import RedirectResponse
 
 from ..utils import db
+from ..utils.models import Error, CRDiff
 
 router = APIRouter(tags=["Diffs"])
 
 
-@router.get("/cr/{old}-{new}", summary="CR diff")
+class DiffError(Error):
+    old: str
+    new: str
+
+
+@router.get(
+    "/cr/{old}-{new}",
+    summary="CR diff",
+    response_model=Union[DiffError, CRDiff],
+    responses={200: {"model": CRDiff}, 404: {"model": DiffError}},
+)
 async def cr_diff(
     response: Response,
     old: str = Path(description="Set code of the old set.", min_length=3, max_length=5),
@@ -15,6 +28,15 @@ async def cr_diff(
     """
     Returns a diff of the CR between the two specified sets. Diffs only exist for neighboring CR releases. The path
     parameters are **not** case sensitive.
+
+    The `changes` property is an ordered array of diff items, with each item consisting of the `old` and `new`
+    versions of a rule. If a new rule is added, `old` is `null`. If an old rule is deleted, `new` is `null`.
+    Otherwise, the differing parts of the `ruleText` string are wrapped between "<<<<" and ">>>>". Rules with
+    identical text but changed rule number aren't part of this array, and neither are rules whose only change in text
+    was a reference to a renumbered rule.
+
+    `source_set` and `dest_set` contain full names of the sets being diffed, and the `nav` property stores set codes
+    of diffs immediately preceding/following this one
     """
     old = old.upper()
     new = new.upper()

app/utils/models.py

@@ -1,4 +1,7 @@
+import datetime
 from typing import Union
+
+import pydantic
 from pydantic import BaseModel
 
 
@@ -35,3 +38,31 @@ class KeywordDict(BaseModel):
 class GlossaryTerm(BaseModel):
     term: str
     definition: str
+
+
+class CRDiffRule(BaseModel):
+    ruleNum: str
+    ruleText: str
+
+
+class CRDiffItem(BaseModel):
+    old: CRDiffRule | None
+    new: CRDiffRule | None
+
+
+class CRDiffNavItem(BaseModel):
+    old: str
+    new: str
+
+
+class CRDiffNav(BaseModel):
+    prev: CRDiffNavItem | None
+    next: CRDiffNavItem | None
+
+
+class CRDiff(BaseModel):
+    creation_day: datetime.date
+    changes: list[CRDiffItem]
+    source_set: str
+    dest_set: str
+    nav: CRDiffNav

docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  api:
+    build: .
+    ports:
+      - "8000:80"
+    environment:
+      # overrides for values set in .env
+      ADMIN_KEY: "super-secret-value"
+      DB_USER: server
+      DB_PASS: password
+      DB_HOST: db
+      DB_DATABASE: academy_ruins
+    volumes:
+      - ./app:/code/app:rw
+      - ./generated:/code/app/resources/generated:rw
+
+
+  db:
+    image: postgres
+    restart: always
+    ports:
+      - 5432:5432
+    environment:
+      POSTGRES_PASSWORD: password