Getting Started

starlette_jsonapi is based on the JSON:API specification. Its mission is to offer the tools for writing a compliant service (written in async Python), while keeping the core data agnostic.

If you are here, you probably agree that the REST paradigm came with a lot of good things, to name a few:

  • intuitive interfaces

  • separation of client-server concerns

  • improved scalability

But without a standard for defining payloads and interactions, things can get messy pretty fast. That’s where JSON:API comes into play. You should go check it out if you haven’t already, it’s full of good intentions.

In a few words, the specification includes a set of rules for exposing and consuming an API, as well as instructions and recommendations for setting up powerful features, similar to those of GraphQL - sparse fieldsets, compound documents - while keeping the overall complexity low.

Since starlette is handling the web parts, and marshmallow + marshmallow-jsonapi the serialization, you are free to choose your own ORM, be it synchronous or asynchronous.

Installing

It is recommended to install starlette-jsonapi from PyPI:

$ pip install starlette-jsonapi

You should also pin its version in the requirements file:

$ pip freeze | grep "starlette-jsonapi" >> requirements.txt

Reading materials

Examples

Head over to GitHub and study the examples directory for full implementations.

You can fire up Postman and try the bundled collection against the example services.

If you like the included examples and wish to add one for an ORM of your choice, feel free to open a pull request.