add: meaningful error responses

main.py

@@ -1,9 +1,11 @@
 from fastapi import FastAPI
+from fastapi.responses import JSONResponse
 
 from datetime import datetime
 from uuid import uuid4
 import sqlite3
 
+
 # use database residing here
 DB_LOCATION = (
     "../testbox/photovoter.dblite"  # Q: any allowances for this being not OUR database?
@@ -15,7 +17,7 @@ con.row_factory = sqlite3.Row
 cur = con.cursor()  # NB! single is enough for now, we might require multiple later
 
 
-@app.get("/new_session")
+@app.get("/new_session", responses={503: {"description": "Unable to initiate session"}})
 async def new_session():
     """Start a new session"""
     # add session to the database
@@ -36,7 +38,7 @@ async def new_session():
             if i < tries - 1 and str(e) == "UNIQUE constraint failed: sessions.cookie":
                 continue
             elif str(e) == "UNIQUE constraint failed: sessions.cookie":
-                return {"cookie": "error"}
+                return JSONResponse(status_code=503)
             else:
                 raise
         break
@@ -45,7 +47,13 @@ async def new_session():
     return {"cookie": cookie}
 
 
-@app.get("/next_picture/{cookie}")
+@app.get(
+    "/next_picture/{cookie}",
+    responses={
+        204: {"description": "All available images have been appraised"},
+        409: {"description": "Uninitiated session"},
+    },
+)
 async def next_picture(cookie: str):
     """Request new picture to rate."""
     # check if the cookie is valid
@@ -58,10 +66,7 @@ async def next_picture(cookie: str):
     )
     sessionid = cur.fetchone()
     if sessionid is None:
-        return {
+        return JSONResponse(status_code=409)
-            "picture_id": -2,
-            "picture_uri": "/path/to/new/session/placeholder",  # FIXME[2]
-        }  # Q: do we return something specific, or just use convention here?
 
     # take not rated picture from the database
     # do not insert anything in the database yet
@@ -88,13 +93,16 @@ async def next_picture(cookie: str):
         return {"picture_id": r["imgid"], "picture_uri": r["resizedpath"]}
     else:
         # All available pics have been voted for by this sessionid
-        return {
+        return JSONResponse(status_code=204)
-            "picture_id": -1,
-            "picture_uri": "/path/to/you/are/done/placeholder",  # FIXME[1]
-        }  # Q: do we return something specific, or just use a convention here?
 
 
-@app.get("/rate_picture/{cookie}/{picture_id}/{mark}")
+@app.get(
+    "/rate_picture/{cookie}/{picture_id}/{mark}",
+    responses={
+        406: {"description": "Already appraised"},
+        409: {"description": "Uninitiated session"},
+    },
+)
 async def rate_picture(cookie: str, picture_id: int, mark: int):
     """Submit a rating for the picture"""
     # check if the cookie is valid
@@ -107,9 +115,7 @@ async def rate_picture(cookie: str, picture_id: int, mark: int):
     )
     sessionid = cur.fetchone()
     if sessionid is None:
-        return {
+        return JSONResponse(status_code=409)
-            "status": "failure"  # FIXME[2]
-        }  # Q: do we return something specific, or just use convention here?
 
     # add new mark to the session table
     try:
@@ -122,6 +128,6 @@ async def rate_picture(cookie: str, picture_id: int, mark: int):
         con.commit()
     except sqlite3.IntegrityError as e:
         if str(e) == "UNIQUE constraint failed: marks.imgid, marks.sessionid":
-            return {"status": "already rated"}
+            return JSONResponse(status_code=406)
 
     return {"status": "success"}