Quickstart

Overview

fairproxy-api exposes FAIR-oriented metadata and platform-native payloads through a unified FastAPI interface.

Current Socrata support includes:

  • Croissant metadata

  • DCAT metadata

  • DDI Codebook XML

  • DDI-CDIF graphs

  • Markdown summaries

  • Postman collection generation

  • Native dataset payloads through /native

Run Locally

From the project directory:

uv sync
uv run uvicorn --app-dir src/dartfx fairproxy_api.main:app --host 0.0.0.0 --port 8000 --reload

From the monorepo root:

uv sync
uv run --package dartfx-fairproxy-api uvicorn --app-dir dartfx-fairproxy-api/src/dartfx fairproxy_api.main:app --host 0.0.0.0 --port 8000 --reload

Health check:

curl http://127.0.0.1:8000/status

Endpoint Examples

Current Top-Level Routes

  • /status for health status

  • /servers for configured data server discovery

  • /datasets/{uri} for unified dataset metadata and native payloads

  • /socrata/{host}/{dataset_id} for Socrata-specific dataset access

Generic routes like /catalog, /resources, and /vocab are intentionally not exposed in the current build.

Socrata URI Format

The unified datasets endpoint expects Socrata URIs in this format:

socrata:<server>:<dataset-id>

Where:

  • socrata is the platform identifier.

  • <server> is the Socrata host (for example, data.sfgov.org).

  • <dataset-id> is the Socrata dataset identifier (for example, wg3w-h783).

Example URI:

socrata:data.sfgov.org:wg3w-h783

Unified dataset routes

curl "http://127.0.0.1:8000/datasets/socrata:data.sfgov.org:wg3w-h783/ddi/codebook"
curl "http://127.0.0.1:8000/datasets/socrata:data.sfgov.org:wg3w-h783/postman/collection"
curl "http://127.0.0.1:8000/datasets/socrata:data.sfgov.org:wg3w-h783/markdown"
curl "http://127.0.0.1:8000/datasets/socrata:data.sfgov.org:wg3w-h783/native"

Socrata-specific routes

curl "http://127.0.0.1:8000/socrata/data.sfgov.org/wg3w-h783/ddi/codebook"
curl "http://127.0.0.1:8000/socrata/data.sfgov.org/wg3w-h783/native"

Native Endpoint Convention

  • /datasets/{uri}/native is the platform-agnostic native payload route.

  • /socrata/{host}/{dataset_id}/native is the Socrata-specific native payload route.

  • The previous /socrata native suffix is obsolete and has been replaced by /native.