API versioning and documentation

Deploying AI into Production with FastAPI

Matt Eckerle

Software and Data Engineering Leader

Why API versioning?

API endpoints as menu items
Keep old customers happy
Some customers want new options
Iterate without impacting existing customers

A restaurant

API for cloud AI jobs

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes

class AIJobV1(BaseModel):
    job_name: str
    data: bytes
    config: dict

Logo of FastAPI AI Cloud

Versioned endpoints

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes


class AIJobV2(BaseModel):
    job_name: str
    data: bytes
    config: dict

from fastapi import FastAPI

app = FastAPI()

@app.post("/v1/ai-job")
def ai_job_v1(job: AIJobV1):
    ...


@app.post("/v2/ai-job")
def ai_job_v2(job: AIJobV2):
    ...

Reasons to update endpoint version

Breaking change in schema
Change in underlying function
- Updated model code
- Updated model training set
- Updated pre/post processing

Iteration with optional fields

Versioning is not always required to iterate
Optional fields can support additional data without breaking schemas

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes


from typing import Optional

class AIJobV1(BaseModel):
    job_name: str
    data: bytes
    config: Optional[dict]

Documenting APIs with Swagger

Standard tool for API documentation
- Keeps track of endpoints and versions
- Built on OpenAPI standard metadata

OpenAPI logo

Swagger UI

Swagger URL Swagger UI

Swagger UI for an endpoint

FastAPI Swagger UI for endpoint

Using FastAPI's description field

from fastapi import FastAPI

app = FastAPI(
    description="AI Job API"
)

FastAPI Swagger UI with description header

Let's practice!

Deploying AI into Production with FastAPI