FastAPI-JSONAPI

FastAPI-JSONAPI is an extension for FastAPI that adds support for quickly building REST APIs with huge flexibility around the JSON:API 1.0 specification. It is designed to fit the complexity of real life environments so FastAPI-JSONAPI helps you to create a logical abstraction of your data called “resource”. It can interface any kind of ORMs or data storage through the concept of data layers.

Main concepts

* JSON:API 1.0 specification: this is a very popular specification for client-server interactions through a JSON-based REST API. It helps you work in a team because it is very precise and sharable. Thanks to this specification your API can offer a lot of features such as a strong structure of request and response, filtering, pagination, sparse fieldsets, including related objects, great error formatting, etc.

* Logical data abstraction: you usually need to expose resources to clients that don’t fit your data table architecture. For example sometimes you don’t want to expose all attributes of a table, compute additional attributes or create a resource that uses data from multiple data storages.

* Data layer: the data layer is a CRUD interface between your resource manager and your data. Thanks to this you can use any data storage or ORM. There is an already full-featured data layer that uses the SQLAlchemy ORM but you can create and use your own custom data layer to use data from your data storage. You can even create a data layer that uses multiple data storage systems and ORMs, send notifications or perform custom actions during CRUD operations.

Features

FastAPI-JSONAPI has many features:

• Relationship management - in developing

• Powerful filtering

• Include related objects - in developing

• Sparse fieldsets - in developing

• Pagination

• Sorting

• Permission management - in developing

• OAuth support - in developing

User’s Guide

This part of the documentation will show you how to get started using FastAPI-JSONAPI with FastAPI.

• Installation
• A minimal API
• Filtering API example
• Quickstart
  • Advanced example
  • Classical CRUD operations
    • Create object
    • List objects
    • Update object
    • Delete object
  • Relationships
    • Create object with related object(s)
    • Update object and his relationships
    • Create relationship
    • Load person with all the related computers
    • Check person’s computers without loading actual person
    • Delete relationship
• Routing
• Filtering
  • SQLAlchemy
  • Simple filters
• Include related objects
• Include nested and related, Many-to-Many
  • Prepare models and schemas
    • Define SQLAlchemy models
    • Define pydantic schemas
    • Define view classes
  • List Parent objects with Children through an Association object
• Custom SQL filtering
  • Prepare pydantic schema which is used in RoutersJSONAPI as schema
  • Search for objects
• Logical data abstraction
• Resource Manager
  • Required attributes
  • ResourceList
  • ResourceDetail
• Data layer
• Sparse fieldsets
• Pagination
  • Size
  • Number
  • Size + Number
  • Disable pagination
• Sorting
  • Multiple sort
  • Descending sort
  • Multiple sort + Descending sort
• Errors
• Permission
• OAuth
• Configuration

• Changelog
  • 1.0.0
  • 0.2.1
  • 0.2.0

A minimal API

This example provides the following API structure:

URL	method	endpoint	Usage
/persons	GET	person_list	Get a collection of persons
/persons	POST	person_list	Create a person
/persons/<int:person_id>	GET	person_detail	Get person details
/persons/<int:person_id>	PATCH	person_detail	Update a person
/persons/<int:person_id>	DELETE	person_detail	Delete a person

Request:

POST /persons HTTP/1.1
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "person",
    "attributes": {
        "name": "John"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "attributes": {
      "name": "John"
    },
    "id": "1",
    "links": {
      "self": "/persons/1"
    },
    "type": "person"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "/persons/1"
  }
}

Request:

GET /persons/1 HTTP/1.1
Content-Type: application/vnd.api+json

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "attributes": {
      "name": "John"
    },
    "id": "1",
    "links": {
      "self": "/persons/1"
    },
    "type": "person"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "/persons/1"
  }
}

Request:

GET /persons HTTP/1.1
Content-Type: application/vnd.api+json

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "attributes": {
        "name": "John"
      },
      "id": "1",
      "links": {
        "self": "/persons/1"
      },
      "type": "person"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "http://localhost:5000/persons"
  },
  "meta": {
    "count": 1
  }
}

Request:

PATCH /persons/1 HTTP/1.1
Content-Type: application/vnd.api+json

{
  "data": {
    "id": 1,
    "type": "person",
    "attributes": {
        "name": "Sam"
    }
  }
}

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "attributes": {
      "name": "Sam"
    },
    "id": "1",
    "links": {
      "self": "/persons/1"
    },
    "type": "person"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "/persons/1"
  }
}

Request:

DELETE /persons/1 HTTP/1.1
Content-Type: application/vnd.api+json

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "message": "Object successfully deleted"
  }
}

API Reference

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

• Index

• Module Index