starlette-api 0.5.0

Starlette API layer inherited from APIStar

Starlette API

• Version: 0.5.0
• Status: Production/Stable
• Author: José Antonio Perdiguero López

Introduction

That library aims to bring a layer on top of Starlette framework to provide useful mechanism for building APIs. It's based on API Star, inheriting some nice ideas like:

• Schema system based on Marshmallow that allows to declare the inputs and outputs of endpoints and provides a reliable way of validate data against those schemas.
• Dependency Injection that ease the process of managing parameters needed in endpoints.
• Components as the base of the plugin ecosystem, allowing you to create custom or use those already defined in your endpoints, injected as parameters.
• Starlette ASGI objects like Request, Response, Session and so on are defined as components and ready to be injected in your endpoints.
• Auto generated API schema using OpenAPI standard. It uses the schema system of your endpoints to extract all the necessary information to generate your API Schema.
• Auto generated docs providing a Swagger UI or ReDocs endpoint.

Requirements

• Python 3.6+
• Starlette 0.10+

Installation

$ pip install starlette-api

Example

from marshmallow import Schema, fields, validate
from starlette_api.applications import Starlette


# Data Schema
class Puppy(Schema):
    id = fields.Integer()
    name = fields.String()
    age = fields.Integer(validate=validate.Range(min=0))


# Database
puppies = [
    {"id": 1, "name": "Canna", "age": 6},
    {"id": 2, "name": "Sandy", "age": 12},
]


# Application
app = Starlette(
    components=[],      # Without custom components
    title="Foo",        # API title
    version="0.1",      # API version
    description="Bar",  # API description
    schema="/schema/",  # Path to expose OpenAPI schema
    docs="/docs/",      # Path to expose Swagger UI docs
    redoc="/redoc/",    # Path to expose ReDoc docs
)


# Views
@app.route("/", methods=["GET"])
def list_puppies(name: str = None) -> Puppy(many=True):
    """
    List the puppies collection. There is an optional query parameter that 
    specifies a name for filtering the collection based on it.
    
    Request example:
    GET http://example.com/?name=Sandy
    
    Response example:
    200
    [
        {"id": 2, "name": "Sandy", "age": 12}
    ]
    """
    return [puppy for puppy in puppies if puppy["name"] == name]
    

@app.route("/", methods=["POST"])
def create_puppy(puppy: Puppy) -> Puppy:
    """
    Create a new puppy using data validated from request body and add it
    to the collection.
    
    Request example:
    POST http://example.com/
    {
        "id": 1,
        "name": "Canna",
        "age": 6
    }
    
    Response example:
    200
    {
        "id": 1,
        "name": "Canna",
        "age": 6
    }
    """
    puppies.append(puppy)
    
    return puppy

Credits

That library started mainly as extracted pieces from APIStar and adapted to work with Starlette.

Contributing

This project is absolutely open to contributions so if you have a nice idea, create an issue to let the community discuss it.