From 3e149433688bf6887d584b3a92f4f85d6ff26359 Mon Sep 17 00:00:00 2001 From: matthewberry Date: Thu, 7 Aug 2025 23:20:13 -0500 Subject: [PATCH] added python examples to swagger docs --- app/main.py | 6 ++- app/routers/data.py | 108 +++++++++++++++++++++++++++++++++++----- app/routers/metadata.py | 49 +++++++++++++----- 3 files changed, 137 insertions(+), 26 deletions(-) diff --git a/app/main.py b/app/main.py index b83e8f4..2827155 100644 --- a/app/main.py +++ b/app/main.py @@ -25,6 +25,11 @@ async def lifespan(app: FastAPI): description=settings.DESCRIPTION + f""" +## Using this Page + +Sections below can be expanded to see detailed information about each endpoint, including parameters, response formats, and example usage. +The "Try it out" feature allows you to interactively test endpoints directly from the documentation. + ## Automatic Pagination When a query would return more than {settings.AUTO_PAGINATION_THRESHOLD} records and no explicit limit is @@ -32,7 +37,6 @@ async def lifespan(app: FastAPI): at a time. The response will include pagination metadata with links to navigate to next and previous pages. -This threshold can be configured using the AUTO_PAGINATION_THRESHOLD environment variable. """, version=settings.VERSION, lifespan=lifespan, diff --git a/app/routers/data.py b/app/routers/data.py index 7d8208b..327dac4 100644 --- a/app/routers/data.py +++ b/app/routers/data.py @@ -83,27 +83,109 @@ async def get_data( db: Database = Depends(get_db), request: Request = None, ) -> Any: - """ - Get enzyme kinetic data with filtering options. + r""" +Get enzyme kinetic data with filtering options. + +This endpoint allows querying the OED database with various filters. + +All filters on the same column are combined with OR logic, while filters on +different columns are combined with AND logic. + +The response format can be either JSON (default) or CSV. + +Results are automatically paginated when they exceed the configured threshold, unless +an explicit limit is provided. + +### URL examples + +- /api/v1/data?organism=Homo%20sapiens&organism=Mus%20musculus + +- /api/v1/data?ec=1.1.%&format=csv&limit=100 + +- /api/v1/data?columns=ec&columns=substrate&columns=organism - This endpoint allows querying the OED database with various filters. +### Python example retrieving JSON data - All filters on the same column are combined with OR logic, while filters on - different columns are combined with AND logic. +```python +import requests + +# Query data using filters based on metadata +params = { + "organism": ["Trichoderma viride", "Salmonella enterica"], # Multiple values use OR logic + "temperature_min": 25, + "temperature_max": 37, + "limit": 10 # Limit to 10 results +} + +response = requests.get("https://fastapi.openenzymedb.mmli1.ncsa.illinois.edu/api/v1/data", params=params) + +if response.status_code == 200: + data = response.json() + print(f"Total matching records: {data['total']}") + print(f"Returning records: {len(data['data'])}") + + # Access the first record + if data["data"]: + first_record = data["data"][0] + print("\nFirst record:") + print(f"EC number: {first_record['ec']}") + print(f"Substrate: {first_record['substrate']}") + print(f"Organism: {first_record['organism']}") + print(f"kcat value: {first_record['kcat_value']} {first_record.get('kcat_unit', '')}") +else: + print(f"Error: {response.status_code} - {response.text}") +``` + +### Python example retrieving CSV data + +```python +import requests +import csv +from io import StringIO - The response format can be either JSON (default) or CSV. +# Query parameters +params = { + "ec": ["1.14.15.16", "5.3.1.9"], # Find data for specific EC numbers + "format": "csv", # Request CSV format + "columns": ["ec", "substrate", "organism", "kcat_value", "km_value"], # Only selected columns + "limit": 20 # Limit to 20 results +} - Results are automatically paginated when they exceed the configured threshold - (default: configurable via AUTO_PAGINATION_THRESHOLD in config.Settings), unless - an explicit limit is provided. +# Make the request +response = requests.get("https://fastapi.openenzymedb.mmli1.ncsa.illinois.edu/api/v1/data", params=params) - Example queries: +if response.status_code == 200: + # Parse CSV data + csv_data = StringIO(response.text) + reader = csv.DictReader(csv_data) - - /api/v1/data?organism=Homo%20sapiens&organism=Mus%20musculus + # Save to file + with open("oed_data_export.csv", "w", newline="") as f: + writer = csv.DictWriter(f, fieldnames=reader.fieldnames) + writer.writeheader() + for row in reader: + writer.writerow(row) - - /api/v1/data?ec=1.1.%&format=csv&limit=100 + print(f"Data saved to oed_data_export.csv") - - /api/v1/data?columns=ec&columns=substrate&columns=organism + # Preview the data + csv_data.seek(0) # Reset to beginning of stream + reader = csv.DictReader(csv_data) + rows = list(reader) + if rows: + print("\nSample of downloaded data:") + for i, row in enumerate(rows[:3]): + print(f"\nRecord {i+1}:") + print(f"EC: {row['ec']}") + print(f"Substrate: {row['substrate']}") + print(f"Organism: {row['organism']}") + if 'kcat_value' in row and row['kcat_value']: + print(f"kcat value: {row['kcat_value']}") + if 'km_value' in row and row['km_value']: + print(f"km value: {row['km_value']}") +else: + print(f"Error: {response.status_code} - {response.text}") +``` """ try: diff --git a/app/routers/metadata.py b/app/routers/metadata.py index 6046356..cdafa21 100644 --- a/app/routers/metadata.py +++ b/app/routers/metadata.py @@ -13,18 +13,43 @@ async def get_metadata( column: OEDColumn, db: Database = Depends(get_db), ) -> OEDColumnValues: - """ - Get distinct values for a specified column. - - This endpoint returns a list of all distinct values for a specified column - in the OED data set. This is useful to inspect what values can be used - for a more targeted download. - - Example query: - - - /api/v1/metadata?column=organism - - - /api/v1/metadata?column=ec + r""" +Get distinct values for a specified column. + +This endpoint returns a list of all distinct values for a specified column +in the OED data set. This is useful to inspect what values can be used +for a more targeted download. + +### URL examples + +- /api/v1/metadata?column=organism + +- /api/v1/metadata?column=ec + +### Python example + +```python +import requests + +# Get distinct organism values to aid in filtering +response = requests.get("https://fastapi.openenzymedb.mmli1.ncsa.illinois.edu/api/v1/metadata", params={"column": "organism"}) + +if response.status_code == 200: + organism_data = response.json() + organisms = organism_data["values"] + print(f"Found {len(organisms)} distinct organism values") + print("Sample organisms:") + for organism in organisms[:5]: # Display first 5 organisms + print(f"- {organism}") + # Sample output might include: + # - Trichoderma viride + # - Paenibacillus thiaminolyticus + # - Naegleria fowleri + # - Rhodococcus rhodochrous + # - Echinosophora koreensis +else: + print(f"Error: {response.status_code} - {response.text}") +``` """ try: values = await get_column_values(db, column=column.value)