:bricks: added new and improved interfaces

.env.sample

@@ -2,9 +2,13 @@ SERVER_NAME=PAULO
 SERVER_HOST=http://localhost
 BACKEND_CORS_ORIGINS=["http://localhost"]
 
+API_V1_STR=/api/v1
+
 PROJECT_NAME=PAULO
 
 POSTGRES_SERVER=localhost
 POSTGRES_USER=paulo
 POSTGRES_PASSWORD=paulo
 POSTGRES_DB=paulo
+
+API_KEYS=[]

app/api.py

 from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
 from starlette.middleware.cors import CORSMiddleware
 from app.config import api_settings
 
 from app import routes
+from app.routes.api_v1.api import api_router
 
 app = FastAPI(
-    title=api_settings.PROJECT_NAME,
+    title=api_settings.PROJECT_NAME, openapi_url=f"{api_settings.API_V1_STR}/openapi.json"
 )
 
 # Set all CORS enabled origins
@@ -18,4 +20,26 @@ if api_settings.BACKEND_CORS_ORIGINS:
         allow_headers=["*"],
     )
 
-app.include_router(routes.courses_router)
+
+# configure openapi
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+
+    openapi_schema = get_openapi(
+        title=f"{api_settings.PROJECT_NAME} API Specification",
+        version="0.1",
+        description=
+        f"The project {api_settings.PROJECT_NAME} is not associated with PAUL at Paderborn University. "
+        f"See the official <a href='https://git.cs.uni-paderborn.de/paulo'>repository</a> for more information.",
+        routes=app.routes,
+    )
+
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+
+app.openapi = custom_openapi
+
+app.include_router(routes.courses_router, deprecated=True, tags=["courses"])
+app.include_router(api_router, prefix=api_settings.API_V1_STR)

app/config/api.py

+import uuid
 from typing import List, Union
 
 from pydantic import BaseSettings, AnyHttpUrl, validator
@@ -21,6 +22,10 @@ class APISettings(BaseSettings):
     
     PROJECT_NAME: str = 'PAULO'
 
+    API_V1_STR: str = '/api/v1'
+
+    API_KEYS: List[uuid.UUID] = []
+
     BROKER: str = 'database'
     
     class Config:

app/data/brokers/broker.py

@@ -16,3 +16,6 @@ class Broker:
 
     def get_courses(self, semester_name: str) -> List[schemas.Course]:
         pass
+
+    def get_semesters(self) -> List[schemas.SemesterWithoutCourses]:
+        pass

app/data/brokers/database.py

@@ -29,3 +29,6 @@ class DatabaseBroker(Broker):
     def get_courses(self, semester_name) -> List[schemas.Course]:
         return self.session.query(models.Course).join(models.Semester).filter(
             models.Semester.name == semester_name).all()
+
+    def get_semesters(self) -> List[schemas.SemesterWithoutCourses]:
+        return self.session.query(models.Semester).all()

app/routes/api_dependencies.py

+from fastapi import Security, HTTPException
+from fastapi.security import APIKeyHeader
+
+from app.config import api_settings
+
+api_key_header = APIKeyHeader(name="API-Key")
+
+
+def check_api_key(api_key: str = Security(api_key_header)):
+    if not (api_key in api_settings.API_KEYS):
+        raise HTTPException(status_code=401, detail="API-Key header invalid")
+    return api_key

app/routes/api_v1/api.py

+from fastapi import APIRouter
+
+from app.routes.api_v1.endpoints import courses, semesters, admin
+
+api_router = APIRouter()
+api_router.include_router(courses.router, prefix="/courses", tags=["courses"])
+api_router.include_router(semesters.router, prefix="/semesters", tags=["semesters"])
+api_router.include_router(admin.router, prefix="/admin", tags=["admin"])

app/routes/api_v1/endpoints/admin.py

+from fastapi import APIRouter, Depends
+
+from app.routes.api_dependencies import check_api_key
+
+router = APIRouter(
+    dependencies=[Depends(check_api_key)]
+)
+

app/routes/api_v1/endpoints/courses.py

+from typing import List
+
+from fastapi import APIRouter, Depends, Query, Path
+
+from app import schemas
+from app.data.brokers import Broker
+from app.routes.dependencies import get_database_broker
+
+router = APIRouter()
+
+
+@router.get("/search", response_model=List[schemas.CourseWithoutAppointments])
+def list_and_search_courses_by_name(semester: str = Query(..., example="Sommer 2022"),
+                                    title: str = Query(..., example="Systemsoftware und"),
+                                    broker: Broker = Depends(get_database_broker)):
+    """
+    List and search courses by name.
+    """
+    return broker.find_courses_by_name(semester, title)
+
+
+@router.get("/{courseId}", response_model=schemas.Course)
+def retrieve_information_of_a_course(semester: str = Query(..., example="Sommer 2022"),
+                                     courseId: str = Path(..., example="L.079.05401"),
+                                     broker: Broker = Depends(get_database_broker)):
+    """
+    Querries course by id with all small groups and appointments.
+    """
+    return broker.find_course_by_id(semester, courseId)

app/routes/api_v1/endpoints/semesters.py

+from typing import List
+
+from fastapi import APIRouter, Depends
+
+from app import schemas
+from app.data.brokers import Broker
+from app.routes.dependencies import get_database_broker
+
+router = APIRouter()
+
+
+@router.get("/available", response_model=List[schemas.SemesterWithoutCourses])
+def see_all_available_semesters(broker: Broker = Depends(get_database_broker)):
+    """
+    Returns all available semesters.
+    """
+    return broker.get_semesters()

app/schemas/__init__.py

-from .course import Course, Appointment, SmallGroup, CourseList, CourseWithoutAppointments, Semester, SemesterList
+from .course import Course, Appointment, SmallGroup, CourseList, CourseWithoutAppointments, Semester, SemesterList, \
+    SemesterWithoutCourses

app/schemas/course.py

@@ -13,6 +13,15 @@ class Appointment(BaseModel):
     class Config:
         orm_mode = True
 
+        schema_extra = {
+            "example": {
+                "start_time": "2020-01-01T12:00:00",
+                "end_time": "2020-01-01T13:00:00",
+                "room": "C1",
+                "instructors": "Prof. Dr. Holger Karl"
+            }
+        }
+
 
 class SmallGroup(BaseModel):
     name: str
@@ -21,6 +30,15 @@ class SmallGroup(BaseModel):
     class Config:
         orm_mode = True
 
+        schema_extra = {
+            "example": {
+                "name": "Gruppe 1",
+                "appointments": [
+                    Appointment.Config.schema_extra["example"]
+                ]
+            }
+        }
+
 
 class CourseWithoutAppointments(BaseModel):
     cid: str
@@ -30,6 +48,14 @@ class CourseWithoutAppointments(BaseModel):
     class Config:
         orm_mode = True
 
+        schema_extra = {
+            "example": {
+                "cid": "L.079.05401",
+                "name": "Systemsoftware und systemnahe Programmierung",
+                "description": ""
+            }
+        }
+
 
 class Course(CourseWithoutAppointments):
     small_groups: List[SmallGroup] = []
@@ -38,13 +64,35 @@ class Course(CourseWithoutAppointments):
     class Config:
         orm_mode = True
 
+        schema_extra = {
+            "example": {
+                "cid": "L.079.05401",
+                "name": "Systemsoftware und systemnahe Programmierung",
+                "description": "",
+                "small_groups": [SmallGroup.Config.schema_extra["example"]],
+                "appointments": [Appointment.Config.schema_extra["example"]]
+            }
+        }
+
 
 class CourseList(BaseModel):
     __root__: List[Course]
 
 
-class Semester(BaseModel):
+class SemesterWithoutCourses(BaseModel):
     name: str
+
+    class Config:
+        orm_mode = True
+
+        schema_extra = {
+            "example": {
+                "name": "Sommer 2022"
+            }
+        }
+
+
+class Semester(SemesterWithoutCourses):
     courses: List[Course] = []
 
     class Config: