API Functionality

JSON:API Basics

• Applies to: Flask and FastAPI
• Best examples: README.md, examples/demo_relationship.py
• Related pages: Relationships and Includes, Filtering, Sorting, Pagination, and Sparse Fieldsets, Content Types and Errors

What SAFRS exposes for each model

For each exposed SQLAlchemy model, SAFRS creates:

• a collection endpoint
• an instance endpoint
• relationship endpoints
• OpenAPI / Swagger documentation for the generated operations

CRUD summary

Typical resource behavior includes:

• GET /Collection
• POST /Collection
• GET /Collection/{id}
• PATCH /Collection/{id}
• DELETE /Collection/{id}

Actual allowed methods can be narrowed with Model.http_methods.

Relationship summary

Relationships get their own endpoints. SAFRS distinguishes:

• to-one relationships
• to-many relationships

Relationship mutation methods depend on the relationship type and whether the parent model allows writes. See Relationships and Includes.

Query parameter families

Collection and relationship reads commonly use:

• include
• filter
• filter[attribute]
• sort
• page[...]
• fields[TYPE]
• exclude

These are documented in more detail on the dedicated pages:

• Filtering
• Sorting, Pagination, and Sparse Fieldsets

Status codes and error summary

Common responses include:

• 200 for successful reads and updates
• 201 for creates
• 400 for invalid requests and validation failures
• 404 for missing resources
• 409 for relationship or constraint conflicts
• 415 for unsupported media types
• 422 for request-shape validation in the FastAPI adapter

Error responses are documented in Content Types and Errors.