Merge pull request #14 from ImagingDataCommons/docs/api-endpoint-descriptions

docs(api): add OpenAPI summaries/descriptions to every REST route

Author: fedorov

src/idc_api/mcp/server.py

@@ -45,8 +45,9 @@
    get_table_schema before SQL. Do not guess values or column names.
 2. build_cohort for attribute filters; run_sql for relational/aggregate questions (read-only
    DuckDB; `index` plus specialized indices joined on SeriesInstanceUID and named for the
-   DICOM Modality they detail — seg_index: what anatomy a SEG segments; ct/mr/pt_index:
-   acquisition; sm/ann: microscopy; …). If a property isn't in list_attributes (e.g.
+   DICOM Modality they detail — seg_index: what anatomy a SEG segments; ct_index, mr_index,
+   pt_index: acquisition; sm_index, ann_index: microscopy; …). If a property isn't in
+   list_attributes (e.g.
    segmented anatomy), check list_tables before concluding it's unavailable. For clinical
    (non-imaging) attributes — staging, demographics, therapy — use list_clinical_tables, then
    get_clinical_table_schema / get_clinical_table to read the rows (or run_sql against
@@ -58,6 +59,7 @@
 respect get_licenses (CC-BY vs CC-BY-NC). See `idc://guide` for the data model, the full tool
 list, and join examples."""
 
+
 # stateless_http=True / json_response=True make the hosted (streamable-http) transport
 # horizontally scalable on Cloud Run.
 #
@@ -251,7 +253,10 @@ def list_analysis_results() -> list[dict]:
 @guard
 def list_attributes() -> list[dict]:
     """List the attributes you can filter a cohort by (name, type, whether categorical).
-    Call this before build_cohort to learn valid filter attribute names."""
+    Call this before build_cohort to learn valid filter attribute names. These are a curated
+    subset of the `index` table chosen for cohort filtering — run_sql can query or filter on any
+    column in any table from list_tables, including `index` columns that are not filter
+    attributes."""
     return [a.model_dump(mode="json") for a in ctx.discovery.list_attributes()]
 
 
@@ -276,8 +281,9 @@ def get_attribute_values(attribute: str, limit: int = 50) -> dict:
 def list_tables() -> dict:
     """List the tables available to run_sql: the main `index`, collection/analysis/version
     metadata tables, and the specialized indices — named `<modality>_index` after the DICOM
-    Modality they describe (seg_index: segmented anatomy of SEG series; ct/mr/pt_index:
-    acquisition parameters; sm/ann: microscopy) plus contrast/volume_geometry/clinical.
+    Modality they describe (seg_index: segmented anatomy of SEG series; ct_index, mr_index,
+    pt_index: acquisition parameters; sm_index, ann_index: microscopy), plus contrast_index,
+    volume_geometry_index, and clinical_index.
     Call this before writing SQL, and whenever a property you need (e.g. what a segmentation
     contains) is not a filterable attribute — it may live in a specialized index. Per-collection
     clinical data tables are listed separately by list_clinical_tables (queried as
@@ -355,8 +361,11 @@ def build_cohort(
 def run_sql(sql: str, max_rows: int = 100) -> dict:
     """Run a read-only SQL SELECT against the IDC index using DuckDB and return the rows.
     Use for anything build_cohort can't express (GROUP BY, joins across tables, custom
-    aggregations, filters on columns that exist only in a specialized index — e.g. segmented
-    anatomy in seg_index). Only a single read-only SELECT/WITH statement is allowed; the
+    aggregations, or filtering on columns that are not filter attributes: the attributes from
+    list_attributes are a curated subset of `index`, so run_sql is how you reach the rest —
+    other `index` columns like SeriesDescription or PatientAge, and columns that exist only in a
+    specialized index such as segmented anatomy in seg_index). Only a single read-only SELECT/WITH
+    statement is allowed; the
     connection is sandboxed (no writes, no file/network access). Call list_tables /
     get_table_schema first to use correct table and column names. The main table is `index`.
     Per-collection clinical tables are in the `clinical` schema (query as `clinical.<table>`,

src/idc_api/rest/app.py

@@ -217,8 +217,10 @@ def C() -> AppContext:
         return app.state.ctx
 
     # --- meta ---
-    @app.get(API_PREFIX, tags=["meta"])
+    @app.get(API_PREFIX, tags=["meta"], summary="API root")
     def root():
+        """Entry point for the API: returns the server and build version, and links to the
+        interactive docs, the OpenAPI schema, and the version endpoint."""
         return {
             "name": "IDC API",
             "server_version": server_version(),  # this server's software/build version
@@ -227,15 +229,18 @@ def root():
             "version_endpoint": f"{API_PREFIX}/version",
         }
 
-    @app.get(f"{API_PREFIX}/health", tags=["meta"])
+    @app.get(f"{API_PREFIX}/health", tags=["meta"], summary="Health check")
     def health():
+        """Liveness probe for the load balancer and uptime checks. Returns `{"status": "ok"}`
+        once the service is up."""
         return {"status": "ok"}
 
     # --- discovery ---
     @app.get(
         f"{API_PREFIX}/version",
         response_model=VersionInfo,
         tags=["discovery"],
+        summary="IDC and server version",
         responses={
             200: {
                 "content": {
@@ -257,12 +262,17 @@ def health():
         },
     )
     def version():
+        """Report the IDC data release served (e.g. `v24`) and the pinned idc-index-data
+        version, plus this server's own software `api_version` (and `build` stamp, if the deploy
+        set one). Use it to confirm which IDC version — and which build of this server —
+        produced a given result."""
         return C().discovery.version()
 
     @app.get(
         f"{API_PREFIX}/stats",
         response_model=Stats,
         tags=["discovery"],
+        summary="Headline totals",
         responses={
             200: {
                 "content": {
@@ -288,109 +298,224 @@ def version():
         },
     )
     def stats():
+        """Headline totals for all of IDC: the number of collections, analysis results,
+        patients, studies, series, and instances, plus the total size in TB."""
         return C().discovery.stats()
 
     @app.get(
         f"{API_PREFIX}/collections",
         response_model=list[CollectionSummary],
         tags=["discovery"],
+        summary="List collections",
     )
     def collections():
+        """List all IDC collections (original imaging datasets) with cancer types, tumor
+        locations, species, and subject counts. Use it to find a `collection_id` to filter
+        on."""
         return C().discovery.list_collections()
 
     @app.get(
         f"{API_PREFIX}/collections/{{collection_id}}",
         response_model=CollectionDetail,
         tags=["discovery"],
+        summary="Collection detail",
     )
     def collection(collection_id: str = Path(..., examples=["nlst"])):
+        """Detailed metadata for one collection: description, subject/series/instance counts,
+        total size, the modalities present, and the license breakdown."""
         return C().discovery.get_collection(collection_id)
 
     @app.get(
         f"{API_PREFIX}/analysis_results",
         response_model=list[AnalysisResult],
         tags=["discovery"],
+        summary="List analysis results",
     )
     def analysis_results():
+        """List IDC analysis results — derived datasets (AI or expert segmentations,
+        annotations, radiomics) layered on the original collections. Use it to find an
+        `analysis_result_id`."""
         return C().discovery.list_analysis_results()
 
     @app.get(
-        f"{API_PREFIX}/attributes", response_model=list[AttributeInfo], tags=["discovery"]
+        f"{API_PREFIX}/attributes",
+        response_model=list[AttributeInfo],
+        tags=["discovery"],
+        summary="List filter attributes",
     )
     def attributes():
+        """List the attributes a cohort can be filtered by (name, type, whether categorical).
+        Use it to learn valid filter attribute names before building a cohort. These are a
+        curated subset of the `index` table chosen for cohort filtering — `/sql` can query or
+        filter on any column in any table listed by `/tables`, including `index` columns that
+        aren't filter attributes."""
         return C().discovery.list_attributes()
 
     @app.get(
         f"{API_PREFIX}/attributes/{{attribute}}/values",
         response_model=AttributeValues,
         tags=["discovery"],
+        summary="Distinct attribute values",
     )
     def attribute_values(
         attribute: str = Path(..., examples=["Modality"]),
         limit: int = Query(100, ge=1, le=10000, examples=[10]),
     ):
+        """Return the distinct values (with counts) of a categorical attribute on the `index`
+        table, e.g. `Modality` or `BodyPartExamined`. Query this before filtering by an attribute
+        so you use real values with the correct casing rather than guessing. The response carries
+        a `truncated` flag: when `false` the list is complete; when `true`, raise `limit` (capped
+        server-side) and re-check."""
         return C().discovery.get_attribute_values(attribute, limit=limit)
 
     # --- schema discovery ---
-    @app.get(f"{API_PREFIX}/tables", response_model=TableList, tags=["query"])
+    @app.get(
+        f"{API_PREFIX}/tables",
+        response_model=TableList,
+        tags=["query"],
+        summary="List queryable tables",
+    )
     def tables():
+        """List the tables available to the SQL endpoint: the main `index`, the collection,
+        analysis, and version metadata tables, and the specialized indices — each named
+        `<modality>_index` after the DICOM Modality it describes (`seg_index`: segmented anatomy
+        of SEG series; `ct_index`, `mr_index`, `pt_index`: acquisition parameters; `sm_index`,
+        `ann_index`: microscopy), plus `contrast_index`, `volume_geometry_index`, and
+        `clinical_index`. Consult it before writing SQL, and whenever a property you need (e.g.
+        what a segmentation contains) is not a filterable attribute — it may live in a
+        specialized index. Per-collection clinical tables are listed separately by
+        `/clinical/tables`."""
         return C().query.list_tables()
 
-    @app.get(f"{API_PREFIX}/tables/{{table}}", response_model=TableSchema, tags=["query"])
+    @app.get(
+        f"{API_PREFIX}/tables/{{table}}",
+        response_model=TableSchema,
+        tags=["query"],
+        summary="Table schema",
+    )
     def table_schema(table: str = Path(..., examples=["index"])):
+        """Return the columns (name, type, description) of a table. Use it to get correct column
+        names before querying `/sql`. Pass `index` for the main series-level table."""
         return C().query.get_table_schema(table)
 
     # --- clinical data ---
     @app.get(
-        f"{API_PREFIX}/clinical/tables", response_model=ClinicalTableList, tags=["clinical"]
+        f"{API_PREFIX}/clinical/tables",
+        response_model=ClinicalTableList,
+        tags=["clinical"],
+        summary="List clinical tables",
     )
     def clinical_tables(collection_id: str | None = Query(None, examples=["nlst"])):
+        """Discover the per-collection clinical (non-imaging) data tables — demographics,
+        diagnoses, cancer staging, therapies, labs, outcomes. Clinical data is not a filterable
+        attribute and is not harmonized across collections, so table and column names vary per
+        collection. Pass `collection_id` to narrow to one collection. Each table is queryable via
+        `/sql` as `clinical.<table_name>` and joins to `index` on
+        `dicom_patient_id = index.PatientID`."""
         return C().clinical.list_clinical_tables(collection_id=collection_id)
 
     @app.get(
         f"{API_PREFIX}/clinical/tables/{{table}}",
         response_model=TableSchema,
         tags=["clinical"],
+        summary="Clinical table schema",
     )
     def clinical_table_schema(table: str = Path(..., examples=["nlst_canc"])):
+        """Return the columns of a clinical table (name, DuckDB type, and a human-readable label
+        from `clinical_index`, since clinical column names are often cryptic). Get the table name
+        from `/clinical/tables`."""
         return C().clinical.get_clinical_table_schema(table)
 
     @app.get(
         f"{API_PREFIX}/clinical/tables/{{table}}/rows",
         response_model=SqlResult,
         tags=["clinical"],
+        summary="Read clinical table rows",
     )
     def clinical_table_rows(
         table: str = Path(..., examples=["nlst_canc"]),
         max_rows: int | None = Query(None, ge=1, le=100000, examples=[100]),
     ):
+        """Return the rows of a clinical table (capped at `max_rows`). Use it to inspect a small
+        clinical table directly; for filtering by clinical attributes or joining to imaging,
+        query `/sql` against `clinical.<table>` instead. Get the table name from
+        `/clinical/tables`."""
         return C().clinical.get_clinical_table(table, max_rows=max_rows)
 
     # --- cohort / manifest ---
-    @app.post(f"{API_PREFIX}/cohort/counts", response_model=CohortCounts, tags=["cohort"])
+    @app.post(
+        f"{API_PREFIX}/cohort/counts",
+        response_model=CohortCounts,
+        tags=["cohort"],
+        summary="Cohort counts",
+    )
     def cohort_counts(filters: CohortFilters):
+        """Return distinct counts for a filtered cohort — patients, studies, series, instances,
+        and total `size_TB` — without the sample rows or download payload. Use it as a fast size
+        check before building a full manifest or downloading. `terms` is `{attribute: [values]}`
+        for equality/IN; `ranges` is `{attribute: {"gte": x, "lte": y}}` for numeric or date
+        ranges."""
         return C().cohort.counts(filters)
 
     @app.post(
-        f"{API_PREFIX}/cohort/manifest", response_model=ManifestResponse, tags=["cohort"]
+        f"{API_PREFIX}/cohort/manifest",
+        response_model=ManifestResponse,
+        tags=["cohort"],
+        summary="Build cohort manifest",
     )
     def cohort_manifest(req: ManifestRequest):
+        """Build a cohort from structured filters and get back distinct counts (patients,
+        studies, series, instances, size_TB), a page of matching series, and a download payload
+        (idc commands plus a manifest preview). `filters.terms` is `{attribute: [values]}` for
+        equality/IN (e.g. `{"Modality": ["MR"]}`); `filters.ranges` is
+        `{attribute: {"gte": x, "lte": y}}` for numeric or date ranges. Discover valid attributes
+        via `/attributes` and valid values via `/attributes/{attribute}/values`. For anything
+        these structured filters can't express, use `/sql`."""
         return C().cohort.build_manifest(
             req.filters, page=req.page, page_size=req.page_size, include_rows=req.include_rows
         )
 
-    @app.post(f"{API_PREFIX}/cohort/manifest.txt", tags=["cohort"])
+    @app.post(
+        f"{API_PREFIX}/cohort/manifest.txt",
+        tags=["cohort"],
+        summary="Cohort manifest (plain text)",
+    )
     def cohort_manifest_text(req: ManifestTextRequest):
+        """Return a plain-text manifest of public download URLs (one `s3://` or `gs://` per
+        series) for a filtered cohort, up to `limit` lines. `source` is `aws` or `gcs`. These are
+        anonymous public URLs — fetch them with s5cmd/gsutil or the `idc` CLI. The response is
+        `text/plain`, one URL per line."""
         text = C().manifest.manifest_text(req.filters, source=req.source, limit=req.limit)
         return PlainTextResponse(text)
 
     # --- guarded SQL ---
-    @app.post(f"{API_PREFIX}/sql", response_model=SqlResult, tags=["query"])
+    @app.post(
+        f"{API_PREFIX}/sql",
+        response_model=SqlResult,
+        tags=["query"],
+        summary="Run read-only SQL",
+    )
     def sql(req: SqlRequest):
+        """Run a single read-only SQL `SELECT`/`WITH` against the IDC index (DuckDB) and return
+        the rows. Use it for anything the cohort filters can't express — GROUP BY, joins across
+        tables, custom aggregations, or filtering on columns that aren't filter attributes. The
+        attributes from `/attributes` are a curated subset of `index`, so `/sql` is how you reach
+        the rest: other `index` columns (e.g. `SeriesDescription`, `PatientAge`) and columns that
+        live only in a specialized index (e.g. segmented anatomy in `seg_index`). The connection
+        is sandboxed: no writes, no file or network access, one statement only. Get correct table
+        and column names from `/tables` and `/tables/{table}` first; the main table is `index`,
+        and per-collection clinical tables are in the `clinical` schema. The result carries a
+        `truncated` flag — when `true` you did not get every row, so narrow or aggregate the
+        query, or raise `max_rows` (clamped to a server ceiling) and re-check."""
         return C().query.run_sql(req.sql, max_rows=req.max_rows)
 
     # --- viewer / citations / licenses ---
-    @app.get(f"{API_PREFIX}/viewer-url", response_model=ViewerURL, tags=["tools"])
+    @app.get(
+        f"{API_PREFIX}/viewer-url",
+        response_model=ViewerURL,
+        tags=["tools"],
+        summary="Viewer URL",
+    )
     def viewer_url(
         series_instance_uid: str | None = Query(
             None,
@@ -402,23 +527,50 @@ def viewer_url(
         ),
         viewer: str | None = Query(None, examples=["ohif_v3"]),
     ):
+        """Return a browser viewer URL (OHIF for radiology, Slim for slide microscopy) for a
+        series or study, so images can be viewed without downloading. Provide a
+        `series_instance_uid` or `study_instance_uid` (obtain one from a cohort manifest or
+        `/sql`)."""
         return C().viewer.get_viewer_url(
             series_instance_uid=series_instance_uid,
             study_instance_uid=study_instance_uid,
             viewer=viewer,
         )
 
-    @app.post(f"{API_PREFIX}/citations", response_model=CitationsResult, tags=["tools"])
+    @app.post(
+        f"{API_PREFIX}/citations",
+        response_model=CitationsResult,
+        tags=["tools"],
+        summary="Cohort citations",
+    )
     def citations(req: CitationsRequest):
+        """Return the publications to cite for a cohort: per-dataset citations (from the cohort's
+        source DOIs) in `citations`, plus the IDC paper in `idc_acknowledgment`.
+        `citation_format` is one of `apa`, `bibtex`, `csl-json`, `turtle`. When publishing
+        results that use IDC data, include the per-dataset citations and acknowledge IDC itself
+        (see the `recommendation` field)."""
         return C().citations.get_citations(req.filters, citation_format=req.citation_format)
 
-    @app.post(f"{API_PREFIX}/licenses", response_model=LicensesResult, tags=["tools"])
+    @app.post(
+        f"{API_PREFIX}/licenses",
+        response_model=LicensesResult,
+        tags=["tools"],
+        summary="Cohort license breakdown",
+    )
     def licenses(filters: CohortFilters):
+        """Return the license breakdown (series count and size per license) for a cohort. Use it
+        to check whether the data is commercial-friendly (CC BY) or non-commercial only
+        (CC BY-NC) before reuse."""
         return C().licenses.get_licenses(filters)
 
     # --- download (local mode only) ---
-    @app.post(f"{API_PREFIX}/download", tags=["tools"])
+    @app.post(f"{API_PREFIX}/download", tags=["tools"], summary="Download cohort (local only)")
     def download(req: DownloadRequest):
+        """Download DICOM files for a selection to a local directory (via idc-index/s5cmd). This
+        works only when the API runs locally on the caller's machine; a hosted deployment returns
+        a clear error, in which case use `/cohort/manifest.txt` or the idc commands instead.
+        Start with `dry_run=true` to report the download size, then set `dry_run=false` to
+        transfer."""
         return C().download.download(
             download_dir=req.download_dir,
             collection_id=req.collection_id,