REST API Reference & Deployment Guide

REST API Reference & Deployment Guide#

The FAIR Data JSON Schema API provides a lightweight, high-performance RESTful web service for schema validation, semantic linting, schema registry exploration, and format conversions (RO-Crate 1.1, CDIF 1.1, and MLCommons Croissant 1.1).

1. OpenAPI Documentation#

The API includes native OpenAPI 3.1.0 interactive documentation:

Interactive Swagger UI: http://localhost:8000/docs
ReDoc API Reference: http://localhost:8000/redoc
Raw OpenAPI Specification: http://localhost:8000/openapi.json
Static Export: Hosted on the distribution site at https://highvaluedata.net/fair-data-schema/dev/api/openapi.json

2. API Endpoints Overview#

Method	Endpoint	Description
`GET`	`/status`	Health check endpoint returning server status, version, and build timestamp
`GET`	`/v1/schemas`	List all registered FAIR Data JSON Schemas
`POST`	`/v1/validate`	Validate a JSON Schema or dataset instance against FAIR meta-schemas
`POST`	`/v1/lint`	Evaluate semantic metadata quality (missing license, unlinked variables, etc.)
`POST`	`/v1/export/ro-crate`	Convert FAIR JSON Schema to RO-Crate 1.1 metadata graph (`@graph`)
`POST`	`/v1/export/cdif`	Convert FAIR JSON Schema to CDIF v1.1 JSON-LD profiles
`POST`	`/v1/export/croissant`	Convert FAIR JSON Schema to MLCommons Croissant 1.1 JSON-LD

3. Hosting & Deployment Options#

Option 1: Built-in CLI Command (Local Dev)#

The CLI subcommand serve launches the API server via Uvicorn:

# Run locally on default port 8000 with auto-reload
fair-data-schema serve --host 127.0.0.1 --port 8000 --reload

Option 2: Programmatic Python Mounting (Sub-App)#

Embed the FAIR schema API into an existing FastAPI application:

from fastapi import FastAPI
from fair_data_schema.server import app as fair_schema_api

main_app = FastAPI(title="My Data Platform")

# Mount as sub-application
main_app.mount("/api/fair", fair_schema_api)

Option 3: Production ASGI Server (Gunicorn / Uvicorn)#

For Linux servers behind a reverse proxy (e.g. NGINX or Caddy):

# Multi-worker Uvicorn
uvicorn fair_data_schema.server:app --host 0.0.0.0 --port 8000 --workers 4

# Or with Gunicorn worker process manager
gunicorn -w 4 -k uvicorn.workers.UvicornWorker fair_data_schema.server:app

Option 4: Containerized Deployment (Docker / Compose)#

Deploy using the provided multi-stage Dockerfile and docker-compose.yml:

# Build multi-platform Docker image (linux/amd64, linux/arm64)
./docker-build.sh

# Build and export compressed image tarball archive to dist/
./docker-build.sh --save

# Build multi-platform image and push to Docker Hub (dartfx/fair-data-schema-api)
./docker-build.sh --push

# Build and run locally with Docker Compose
docker-compose up -d --build

# Check status
docker-compose ps

Option 5: Serverless & Cloud Deployments#

Deploy to serverless platforms using Mangum (AWS Lambda / API Gateway) or container platforms (Fly.io / Render / GCP Cloud Run):

# lambda_function.py
from mangum import Mangum
from fair_data_schema.server import app

handler = Mangum(app)