From 12db1e646fa3e2bcdc83022ee710efc99b983c34 Mon Sep 17 00:00:00 2001
From: pcain-usgs <pcain@usgs.gov>
Date: Wed, 14 Jul 2021 13:34:49 -0600
Subject: [PATCH] Document data ws endpoints
---
geomagio/api/ws/algorithms.py | 14 ++++++++++++--
geomagio/api/ws/data.py | 7 ++++++-
geomagio/api/ws/elements.py | 5 ++++-
geomagio/api/ws/metadata.py | 8 ++++++--
geomagio/api/ws/observatories.py | 10 ++++++++--
5 files changed, 36 insertions(+), 8 deletions(-)
diff --git a/geomagio/api/ws/algorithms.py b/geomagio/api/ws/algorithms.py
index bcc42a359..fe6d32078 100644
--- a/geomagio/api/ws/algorithms.py
+++ b/geomagio/api/ws/algorithms.py
@@ -1,3 +1,4 @@
+from os import name
from fastapi import APIRouter, Depends, HTTPException
from starlette.responses import Response
@@ -14,7 +15,11 @@ from .data import format_timeseries, get_data_factory, get_data_query, get_times
router = APIRouter()
-@router.get("/algorithms/dbdt/")
+@router.get(
+ "/algorithms/dbdt/",
+ description="First order derivative at requested interval",
+ name="Dbdt Algorithm",
+)
def get_dbdt(
query: DataApiQuery = Depends(get_data_query),
data_factory: TimeseriesFactory = Depends(get_data_factory),
@@ -31,7 +36,12 @@ def get_dbdt(
)
-@router.post("/algorithms/residual", response_model=Reading)
+@router.post(
+ "/algorithms/residual",
+ description="Caclulates new absolutes and baselines from reading\n\n"
+ + "Returns posted reading object with updated values",
+ response_model=Reading,
+)
def calculate_residual(reading: Reading, adjust_reference: bool = True):
try:
return calculate(reading=reading, adjust_reference=adjust_reference)
diff --git a/geomagio/api/ws/data.py b/geomagio/api/ws/data.py
index 873de6db1..bec7e546e 100644
--- a/geomagio/api/ws/data.py
+++ b/geomagio/api/ws/data.py
@@ -158,7 +158,12 @@ def get_timeseries(data_factory: TimeseriesFactory, query: DataApiQuery) -> Stre
router = APIRouter()
-@router.get("/data/")
+@router.get(
+ "/data/",
+ name="Request data",
+ description="Returns timeseries depending on query parameters\n\n"
+ + "Limited to 345600 data points",
+)
def get_data(
query: DataApiQuery = Depends(get_data_query),
) -> Response:
diff --git a/geomagio/api/ws/elements.py b/geomagio/api/ws/elements.py
index a1379ad77..06da476a8 100644
--- a/geomagio/api/ws/elements.py
+++ b/geomagio/api/ws/elements.py
@@ -8,7 +8,10 @@ from .Element import ELEMENTS
router = APIRouter()
-@router.get("/elements/")
+@router.get(
+ "/elements/",
+ description="Information regarding available geomagnetic elements",
+)
def get_elements() -> Dict:
features = []
for e in ELEMENTS:
diff --git a/geomagio/api/ws/metadata.py b/geomagio/api/ws/metadata.py
index 300dc3340..fb5627a05 100644
--- a/geomagio/api/ws/metadata.py
+++ b/geomagio/api/ws/metadata.py
@@ -10,7 +10,11 @@ from ..db import MetadataDatabaseFactory
router = APIRouter()
-@router.get("/metadata", response_model=List[Metadata])
+@router.get(
+ "/metadata",
+ description="Search metadata records with query parameters(excludes id and metadata id)",
+ response_model=List[Metadata],
+)
async def get_metadata(
category: MetadataCategory = None,
starttime: UTCDateTime = None,
@@ -36,6 +40,6 @@ async def get_metadata(
status=status,
)
metas = await MetadataDatabaseFactory(database=database).get_metadata(
- **query.datetime_dict(exclude={"id"})
+ **query.datetime_dict(exclude={"id", "metadata_id"})
)
return metas
diff --git a/geomagio/api/ws/observatories.py b/geomagio/api/ws/observatories.py
index 3e4fe928c..1a8c797c2 100644
--- a/geomagio/api/ws/observatories.py
+++ b/geomagio/api/ws/observatories.py
@@ -8,7 +8,10 @@ from .Observatory import OBSERVATORIES, OBSERVATORY_INDEX
router = APIRouter()
-@router.get("/observatories/")
+@router.get(
+ "/observatories/",
+ description="Information regarding available geomagnetic observatories",
+)
def get_observatories() -> Dict:
return {
"type": "FeatureCollection",
@@ -16,7 +19,10 @@ def get_observatories() -> Dict:
}
-@router.get("/observatories/{id}")
+@router.get(
+ "/observatories/{id}",
+ description="Search observatories by 3-letter observatory code",
+)
async def get_observatory_by_id(id: str) -> Dict:
try:
return OBSERVATORY_INDEX[id].geojson()
--
GitLab