api: add better response documentation

api/src/dooris_api/models.py

@@ -1,7 +1,37 @@
-from typing import Optional
+from typing import Optional, Self
 from datetime import datetime
-from pydantic import BaseModel
+from pydantic import BaseModel, HttpUrl
+from enum import Enum
 from simple_openid_connect.data import IdToken
+from starlette.datastructures import URL
+from fastapi import status
+
+
+class HttpProblemType(Enum):
+    """
+    Statically known HTTP problem types using the [type URI scheme](https://datatracker.ietf.org/doc/rfc4151/)  
+    """
+    UNAUTHORIZED = "type:noc@hamburg.ccc.de,2026:UNAUTHORIZED"
+    DOOR_NOT_FOUND = "type:noc@hamburg.ccc.de,2026:DOOR_NOT_FOUND"
+
+
+class HttpProblemDetail(BaseModel):
+    """
+    API Error modeled after [RFC9475](https://www.rfc-editor.org/rfc/rfc9457.html).
+    """
+    status: int
+    type: HttpProblemType
+    title: str
+    detail: str
+    instance: Optional[HttpUrl]
+
+    @classmethod
+    def new_unauthorized(cls, request_uri: str | URL) -> Self:
+        return cls(type=HttpProblemType.UNAUTHORIZED, status=status.HTTP_401_UNAUTHORIZED, title="Unauthorized", detail="You tried to access a ressource which requires authentication but you are not authenticated", instance=HttpUrl(str(request_uri)))
+
+    @classmethod
+    def new_door_not_found(cls, requested_door: str, request_uri: str | URL) -> Self:
+        return cls(type=HttpProblemType.DOOR_NOT_FOUND, status=status.HTTP_404_NOT_FOUND, title="Door not found", detail=f"You tried to interact with door {requested_door!r} that is not known to dooris", instance=str(request_uri))
 
 
 class CurrentUser(BaseModel):
@@ -14,6 +44,18 @@ class UserInfo(BaseModel):
 
 class UserStatus(BaseModel):
     is_logged_in: bool
-    guaranteed_session_until: datetime
+    guaranteed_session_until: Optional[datetime]
     user_info: Optional[UserInfo]
 
+
+class DoorStatus(Enum):
+    OPEN = "open"
+    CLOSED = "closed"
+    UNKNOWN = "unknown"
+
+
+class Door(BaseModel):
+    name: str
+    description: str
+    status: DoorStatus
+