diff --git a/API/auth/__init__.py b/API/auth/__init__.py index 0ff71d79..6428d559 100644 --- a/API/auth/__init__.py +++ b/API/auth/__init__.py @@ -1,6 +1,7 @@ from enum import Enum from typing import Union +from fastapi.security import APIKeyHeader from fastapi import Depends, Header, HTTPException from osm_login_python.core import Auth from pydantic import BaseModel, Field @@ -9,6 +10,11 @@ from src.config import get_oauth_credentials +Raw_Data_Access_Token = APIKeyHeader( + name="Access_Token", description="Access Token to Authorize User" +) + + class UserRole(Enum): ADMIN = 1 STAFF = 2 @@ -21,6 +27,16 @@ class AuthUser(BaseModel): img_url: Union[str, None] role: UserRole = Field(default=UserRole.GUEST.value) + class Config: + json_schema_extra = { + "example": { + "id": "123", + "username": "HOT Team", + "img_url": "https://hotteamimage.com", + "role": UserRole.GUEST.value, + } + } + osm_auth = Auth(*get_oauth_credentials()) @@ -43,11 +59,15 @@ def get_osm_auth_user(access_token): return user -def login_required(access_token: str = Header(...)): +def login_required(access_token: str = Depends(Raw_Data_Access_Token)): return get_osm_auth_user(access_token) -def get_optional_user(access_token: str = Header(default=None)) -> AuthUser: +def get_optional_user( + access_token: str = Header( + default=None, description="Access Token to Authorize User" + ) +) -> AuthUser: if access_token: return get_osm_auth_user(access_token) else: @@ -58,7 +78,7 @@ def get_optional_user(access_token: str = Header(default=None)) -> AuthUser: def admin_required(user: AuthUser = Depends(login_required)): db_user = get_user_from_db(user.id) if not db_user["role"] is UserRole.ADMIN.value: - raise HTTPException(status_code=403, detail="User is not an admin") + raise HTTPException(status_code=403, detail=[{"msg": "User is not an admin"}]) return user @@ -70,5 +90,5 @@ def staff_required(user: AuthUser = Depends(login_required)): db_user["role"] is UserRole.STAFF.value or db_user["role"] is UserRole.ADMIN.value ): - raise HTTPException(status_code=403, detail="User is not a staff") + raise HTTPException(status_code=403, detail=[{"msg": "User is not a staff"}]) return user diff --git a/API/auth/routers.py b/API/auth/routers.py index 438a28e4..817125c6 100644 --- a/API/auth/routers.py +++ b/API/auth/routers.py @@ -1,16 +1,32 @@ import json -from fastapi import APIRouter, Depends, Request +from fastapi import APIRouter, Depends, Request, Query, Path from pydantic import BaseModel from src.app import Users +from src.validation.models import ErrorMessage, common_responses from . import AuthUser, admin_required, login_required, osm_auth, staff_required router = APIRouter(prefix="/auth", tags=["Auth"]) -@router.get("/login/") +@router.get( + "/login", + responses={ + 200: { + "description": "A Login URL", + "content": { + "application/json": { + "example": { + "login_url": "https://www.openstreetmap.org/oauth2/authorize/" + } + } + }, + }, + 500: {"model": ErrorMessage}, + }, +) def login_url(request: Request): """Generate Login URL for authentication using OAuth2 Application registered with OpenStreetMap. Click on the download url returned to get access_token. @@ -25,7 +41,7 @@ def login_url(request: Request): return login_url -@router.get("/callback/") +@router.get("/callback", responses={500: {"model": ErrorMessage}}) def callback(request: Request): """Performs token exchange between OpenStreetMap and Raw Data API @@ -42,18 +58,27 @@ def callback(request: Request): return access_token -@router.get("/me/", response_model=AuthUser) +@router.get( + "/me", + response_model=AuthUser, + responses={**common_responses}, + response_description="User Information", +) def my_data(user_data: AuthUser = Depends(login_required)): """Read the access token and provide user details from OSM user's API endpoint, also integrated with underpass . Parameters:None - Returns: user_data + Returns: user_data\n User Role : ADMIN = 1 STAFF = 2 GUEST = 3 + + Raises: + - HTTPException 403: Due to authentication error(Wrong access token). + - HTTPException 500: Internal server error. """ return user_data @@ -62,9 +87,19 @@ class User(BaseModel): osm_id: int role: int + class Config: + json_schema_extra = {"example": {"osm_id": 123, "role": 1}} + # Create user -@router.post("/users/", response_model=dict) +@router.post( + "/users", + response_model=dict, + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 123}}}}, + }, +) async def create_user(params: User, user_data: AuthUser = Depends(admin_required)): """ Creates a new user and returns the user's information. @@ -80,15 +115,26 @@ async def create_user(params: User, user_data: AuthUser = Depends(admin_required - Dict[str, Any]: A dictionary containing the osm_id of the newly created user. Raises: - - HTTPException: If the user creation fails. + - HTTPException 403: If the user creation fails due to insufficient permission. + - HTTPException 500: If the user creation fails due to internal server error. """ auth = Users() return auth.create_user(params.osm_id, params.role) # Read user by osm_id -@router.get("/users/{osm_id}", response_model=dict) -async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)): +@router.get( + "/users/{osm_id}", + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 1, "role": 2}}}}, + "404": {"model": ErrorMessage}, + }, +) +async def read_user( + osm_id: int = Path(description="The OSM ID of the User to Retrieve"), + user_data: AuthUser = Depends(staff_required), +): """ Retrieves user information based on the given osm_id. User Role : @@ -103,7 +149,9 @@ async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)): - Dict[str, Any]: A dictionary containing user information. Raises: - - HTTPException: If the user with the given osm_id is not found. + - HTTPException 403: If the user has insufficient permission. + - HTTPException 404: If the user with the given osm_id is not found. + - HTTPException 500: If it fails due to internal server error. """ auth = Users() @@ -111,9 +159,18 @@ async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)): # Update user by osm_id -@router.put("/users/{osm_id}", response_model=dict) +@router.put( + "/users/{osm_id}", + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 1, "role": 1}}}}, + "404": {"model": ErrorMessage}, + }, +) async def update_user( - osm_id: int, update_data: User, user_data: AuthUser = Depends(admin_required) + update_data: User, + user_data: AuthUser = Depends(admin_required), + osm_id: int = Path(description="The OSM ID of the User to Update"), ): """ Updates user information based on the given osm_id. @@ -129,15 +186,27 @@ async def update_user( - Dict[str, Any]: A dictionary containing the updated user information. Raises: - - HTTPException: If the user with the given osm_id is not found. + - HTTPException 403: If the user has insufficient permission. + - HTTPException 404: If the user with the given osm_id is not found. + - HTTPException 500: If it fails due to internal server error. """ auth = Users() return auth.update_user(osm_id, update_data) # Delete user by osm_id -@router.delete("/users/{osm_id}", response_model=dict) -async def delete_user(osm_id: int, user_data: AuthUser = Depends(admin_required)): +@router.delete( + "/users/{osm_id}", + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 1, "role": 1}}}}, + "404": {"model": ErrorMessage}, + }, +) +async def delete_user( + user_data: AuthUser = Depends(admin_required), + osm_id: int = Path(description="The OSM ID of the User to Delete"), +): """ Deletes a user based on the given osm_id. @@ -148,16 +217,29 @@ async def delete_user(osm_id: int, user_data: AuthUser = Depends(admin_required) - Dict[str, Any]: A dictionary containing the deleted user information. Raises: - - HTTPException: If the user with the given osm_id is not found. + - HTTPException 403: If the user has insufficient permission. + - HTTPException 404: If the user with the given osm_id is not found. + - HTTPException 500: If it fails due to internal server error. """ auth = Users() return auth.delete_user(osm_id) # Get all users -@router.get("/users/", response_model=list) +@router.get( + "/users", + response_model=list, + responses={ + **common_responses, + "200": { + "content": {"application/json": {"example": [{"osm_id": 1, "role": 2}]}} + }, + }, +) async def read_users( - skip: int = 0, limit: int = 10, user_data: AuthUser = Depends(staff_required) + skip: int = Query(0, description="The Number of Users to Skip"), + limit: int = Query(10, description="The Maximum Number of Users to Retrieve"), + user_data: AuthUser = Depends(staff_required), ): """ Retrieves a list of users with optional pagination. @@ -168,6 +250,10 @@ async def read_users( Returns: - List[Dict[str, Any]]: A list of dictionaries containing user information. + + Raises: + - HTTPException 403: If it fails due to insufficient permission. + - HTTPException 500: If it fails due to internal server error. """ auth = Users() return auth.read_users(skip, limit) diff --git a/API/custom_exports.py b/API/custom_exports.py index da4bcea1..8d5c5d67 100644 --- a/API/custom_exports.py +++ b/API/custom_exports.py @@ -5,7 +5,7 @@ from src.config import DEFAULT_QUEUE_NAME from src.config import LIMITER as limiter from src.config import RATE_LIMIT_PER_MIN -from src.validation.models import DynamicCategoriesModel +from src.validation.models import DynamicCategoriesModel, ErrorMessage, common_responses from .api_worker import process_custom_request from .auth import AuthUser, UserRole, staff_required @@ -13,7 +13,23 @@ router = APIRouter(prefix="/custom", tags=["Custom Exports"]) -@router.post("/snapshot/") +@router.post( + "/snapshot", + responses={ + **common_responses, + "429": {"model": ErrorMessage}, + "200": { + "content": { + "application/json": { + "example": { + "task_id": "3fded368-456f-4ef4-a1b8-c099a7f77ca4", + "track_link": "/tasks/status/3fded368-456f-4ef4-a1b8-c099a7f77ca4/", + } + } + } + }, + }, +) @limiter.limit(f"{RATE_LIMIT_PER_MIN}/minute") @version(1) async def process_custom_requests( diff --git a/API/main.py b/API/main.py index f887895a..56d775a6 100644 --- a/API/main.py +++ b/API/main.py @@ -75,7 +75,12 @@ os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1" -app = FastAPI(title="Raw Data API ", swagger_ui_parameters={"syntaxHighlight": False}) +app = FastAPI( + title="Raw Data API ", + description="""The Raw Data API allows you to transform + and export OpenStreetMap (OSM) data in different GIS file formats""", + swagger_ui_parameters={"syntaxHighlight": False}, +) app.include_router(auth_router) app.include_router(raw_data_router) app.include_router(tasks_router) diff --git a/API/raw_data.py b/API/raw_data.py index 441def4c..db16d68e 100644 --- a/API/raw_data.py +++ b/API/raw_data.py @@ -25,7 +25,7 @@ # Third party imports import redis from area import area -from fastapi import APIRouter, Body, Depends, HTTPException, Request +from fastapi import APIRouter, Body, Depends, HTTPException, Request, Path, Query from fastapi.responses import JSONResponse from fastapi_versioning import version @@ -44,6 +44,8 @@ RawDataCurrentParamsBase, SnapshotResponse, StatusResponse, + ErrorMessage, + common_responses, ) from .api_worker import process_raw_data @@ -54,15 +56,26 @@ redis_client = redis.StrictRedis.from_url(CELERY_BROKER_URL) -@router.get("/status/", response_model=StatusResponse) +@router.get( + "/status", response_model=StatusResponse, responses={"500": {"model": ErrorMessage}} +) @version(1) def check_database_last_updated(): - """Gives status about how recent the osm data is , it will give the last time that database was updated completely""" + """Gives status about how recent the osm data is. It will give the last time that database was updated completely""" + result = RawData().check_status() return {"last_updated": result} -@router.post("/snapshot/", response_model=SnapshotResponse) +@router.post( + "/snapshot", + response_model=SnapshotResponse, + responses={ + **common_responses, + 404: {"model": ErrorMessage}, + 429: {"model": ErrorMessage}, + }, +) @limiter.limit(f"{export_rate_limit}/minute") @version(1) def get_osm_current_snapshot_as_file( @@ -414,7 +427,7 @@ def get_osm_current_snapshot_as_file( status_code=403, detail=[ { - "msg": "Insufficient Permission to use folder structure exports , Remove / from filename or get access" + "msg": "Insufficient Permission to use folder structure exports, Remove / from filename or get access" } ], ) @@ -464,7 +477,9 @@ def get_osm_current_snapshot_as_file( ) -@router.post("/snapshot/plain/") +@router.post( + "/snapshot/plain", responses={**common_responses, 404: {"model": ErrorMessage}} +) @version(1) def get_osm_current_snapshot_as_plain_geojson( request: Request, @@ -475,7 +490,7 @@ def get_osm_current_snapshot_as_plain_geojson( Args: request (Request): _description_ - params (RawDataCurrentParamsBase): Same as /snapshot excpet multiple output format options and configurations + params (RawDataCurrentParamsBase): Same as /snapshot except multiple output format options and configurations Returns: Featurecollection: Geojson @@ -496,14 +511,39 @@ def get_osm_current_snapshot_as_plain_geojson( return result -@router.get("/countries/") +@router.get("/countries", responses={"500": {"model": ErrorMessage}}) @version(1) -def get_countries(q: str = ""): +def get_countries( + q: str = Query("", description="Query parameter for filtering countries") +): + """ + Gets Countries list from the database + + Args: + q (str): query parameter for filtering countries + + Returns: + featurecollection: geojson of country + """ + result = RawData().get_countries_list(q) return result -@router.get("/osm_id/") +@router.get( + "/osm_id", + responses={"404": {"model": ErrorMessage}, "500": {"model": ErrorMessage}}, +) @version(1) -def get_osm_feature(osm_id: int): +def get_osm_feature(osm_id: int = Path(description="The OSM ID of feature")): + """ + Gets geometry of osm_id in geojson + + Args: + osm_id (int): osm_id of feature + + Returns: + featurecollection: Geojson + """ + return RawData().get_osm_feature(osm_id) diff --git a/API/stats.py b/API/stats.py index b2ca5414..49a12bb2 100644 --- a/API/stats.py +++ b/API/stats.py @@ -6,12 +6,15 @@ from src.app import PolygonStats from src.config import LIMITER as limiter from src.config import POLYGON_STATISTICS_API_RATE_LIMIT -from src.validation.models import StatsRequestParams +from src.validation.models import StatsRequestParams, stats_response router = APIRouter(prefix="/stats", tags=["Stats"]) -@router.post("/polygon/") +@router.post( + "/polygon", + responses={**stats_response}, +) @limiter.limit(f"{POLYGON_STATISTICS_API_RATE_LIMIT}/minute") @version(1) async def get_polygon_stats( diff --git a/API/tasks.py b/API/tasks.py index 51c51561..656c3304 100644 --- a/API/tasks.py +++ b/API/tasks.py @@ -5,13 +5,13 @@ # Third party imports import redis from celery.result import AsyncResult -from fastapi import APIRouter, Depends, HTTPException, Query, Request +from fastapi import APIRouter, Depends, HTTPException, Query, Request, Path from fastapi.responses import JSONResponse from fastapi_versioning import version # Reader imports from src.config import CELERY_BROKER_URL, DEFAULT_QUEUE_NAME, ONDEMAND_QUEUE_NAME -from src.validation.models import SnapshotTaskResponse +from src.validation.models import SnapshotTaskResponse, ErrorMessage, common_responses from .api_worker import celery from .auth import AuthUser, admin_required, login_required, staff_required @@ -19,10 +19,14 @@ router = APIRouter(prefix="/tasks", tags=["Tasks"]) -@router.get("/status/{task_id}/", response_model=SnapshotTaskResponse) +@router.get( + "/status/{task_id}", + response_model=SnapshotTaskResponse, + responses={"404": {"model": ErrorMessage}, "500": {"model": ErrorMessage}}, +) @version(1) def get_task_status( - task_id, + task_id=Path(description="Unique id provided on response from */snapshot/*"), only_args: bool = Query( default=False, description="Fetches arguments of task", @@ -81,10 +85,26 @@ def get_task_status( return JSONResponse(result) -@router.get("/revoke/{task_id}/") +@router.get( + "/revoke/{task_id}", + responses={ + **common_responses, + "404": {"model": ErrorMessage}, + "200": { + "content": { + "application/json": { + "example": {"id": "aa539af6-83d4-4aa3-879e-abf14fffa03f"} + } + } + }, + }, +) @version(1) -def revoke_task(task_id, user: AuthUser = Depends(staff_required)): - """Revokes task , Terminates if it is executing +def revoke_task( + task_id=Path(description="Unique id provided on response from */snapshot*"), + user: AuthUser = Depends(staff_required), +): + """Revokes task, Terminates if it is executing Args: task_id (_type_): task id of raw data task @@ -96,7 +116,19 @@ def revoke_task(task_id, user: AuthUser = Depends(staff_required)): return JSONResponse({"id": task_id}) -@router.get("/inspect/") +@router.get( + "/inspect", + responses={ + "500": {"model": ErrorMessage}, + "200": { + "content": { + "application/json": { + "example": {"active": [{"celery@default_worker": {}}]} + } + } + }, + }, +) @version(1) def inspect_workers( request: Request, @@ -137,7 +169,19 @@ def inspect_workers( return JSONResponse(content=response_data) -@router.get("/ping/") +@router.get( + "/ping", + responses={ + "500": {"model": ErrorMessage}, + "200": { + "content": { + "application/json": { + "example": {"celery@default_worker": {"ok": "pong"}} + } + } + }, + }, +) @version(1) def ping_workers(): """Pings available workers @@ -148,12 +192,22 @@ def ping_workers(): return JSONResponse(inspected_ping) -@router.get("/purge/") +@router.get( + "/purge", + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"tasks_discarded": 0}}}}, + }, +) @version(1) def discard_all_waiting_tasks(user: AuthUser = Depends(admin_required)): """ Discards all waiting tasks from the queue + Returns : Number of tasks discarded + + Raises: + - HTTPException 403: If purge fails due to insufficient permission. """ purged = celery.control.purge() return JSONResponse({"tasks_discarded": purged}) @@ -162,9 +216,23 @@ def discard_all_waiting_tasks(user: AuthUser = Depends(admin_required)): queues = [DEFAULT_QUEUE_NAME, ONDEMAND_QUEUE_NAME] -@router.get("/queue/") +@router.get( + "/queue", + responses={ + "500": {"model": ErrorMessage}, + "200": { + "content": {"application/json": {"example": {"raw_daemon": {"length": 0}}}} + }, + }, +) @version(1) def get_queue_info(): + """ + Get all the queues + + Returns : The queues names and their lengths + """ + queue_info = {} redis_client = redis.StrictRedis.from_url(CELERY_BROKER_URL) @@ -179,17 +247,31 @@ def get_queue_info(): return JSONResponse(content=queue_info) -@router.get("/queue/details/{queue_name}/") +@router.get( + "/queue/details/{queue_name}", + responses={**common_responses, "404": {"model": ErrorMessage}}, +) @version(1) def get_list_details( - queue_name: str, + queue_name=Path(description="Name of queue to retrieve"), args: bool = Query( default=False, description="Includes arguments of task", ), ): + """ + Retrieves queue information based on the given queue name + + Args: + - queue_name (str): The name of the queue to retrieve. + + Returns : The queue details + """ + if queue_name not in queues: - raise HTTPException(status_code=404, detail=f"Queue '{queue_name}' not found") + raise HTTPException( + status_code=404, detail=[{"msg": f"Queue '{queue_name}' not found"}] + ) redis_client = redis.StrictRedis.from_url(CELERY_BROKER_URL) list_items = redis_client.lrange(queue_name, 0, -1) diff --git a/src/validation/models.py b/src/validation/models.py index 2ff45ab3..5fc5f6f6 100644 --- a/src/validation/models.py +++ b/src/validation/models.py @@ -249,8 +249,8 @@ class SnapshotResponse(BaseModel): class Config: json_schema_extra = { "example": { - "task_id": "aa539af6-83d4-4aa3-879e-abf14fffa03f", - "track_link": "/tasks/status/aa539af6-83d4-4aa3-879e-abf14fffa03f/", + "taskId": "aa539af6-83d4-4aa3-879e-abf14fffa03f", + "trackLink": "/tasks/status/aa539af6-83d4-4aa3-879e-abf14fffa03f/", } } @@ -293,6 +293,67 @@ class Config: json_schema_extra = {"example": {"lastUpdated": "2022-06-27 19:59:24+05:45"}} +class ErrorDetail(BaseModel): + msg: str + + +class ErrorMessage(BaseModel): + detail: List[ErrorDetail] + + +common_responses = { + 401: { + "model": ErrorMessage, + "content": { + "application/json": { + "example": {"detail": [{"msg": "OSM Authentication failed"}]} + } + }, + }, + 403: { + "model": ErrorMessage, + "content": { + "application/json": { + "example": {"detail": [{"msg": "OSM Authentication failed"}]} + } + }, + }, + 500: {"model": ErrorMessage}, +} + +stats_response = { + "200": { + "content": { + "application/json": { + "example": { + "summary": {"buildings": "", "roads": ""}, + "raw": { + "population": 0, + "populatedAreaKm2": 0, + "averageEditTime": 0, + "lastEditTime": 0, + "osmUsersCount": 0, + "osmBuildingCompletenessPercentage": 0, + "osmRoadsCompletenessPercentage": 0, + "osmBuildingsCount": 0, + "osmHighwayLengthKm": 0, + "aiBuildingsCountEstimation": 0, + "aiRoadCountEstimationKm": 0, + "buildingCount6Months": 0, + "highwayLength6MonthsKm": 0, + }, + "meta": { + "indicators": "https://github.com/hotosm/raw-data-api/tree/develop/docs/src/stats/indicators.md", + "metrics": "https://github.com/hotosm/raw-data-api/tree/develop/docs/src/stats/metrics.md", + }, + } + } + } + }, + "500": {"model": ErrorMessage}, +} + + class StatsRequestParams(BaseModel, GeometryValidatorMixin): iso3: Optional[str] = Field( default=None,