Skip to main content

REST support for bareASGI

Project description


This package provides enhanced support for writing REST APIs with bareASGI, (read the docs).

It includes:

  • A router to simplify the creation of REST APIs,
  • A swagger API endpoint

This is a Python 3.7+ package, and is currently pre-release.


The package can be install from pypi.

It is currently pre-release so you will need the --pre flag.

$ pip install --pre bareASGI-rest

An ASGI server will be required to run the code. The examples below use uvicorn.

$ pip install uvicorn


The router provided by this package maps the arguments and types of request handlers.

We will create a mock book repository.

Creating typed dictionaries

Here is the type of a book. We use TypedDict to allow automatic type discovery

from datetime import datetime
    # Available in 3.8
    from typing import TypedDict  # type:ignore
    # Available in 3.7
    from typing_extensions import TypedDict

class Book(TypedDict):
    """A Book

        book_id (int): The book id
        title (str): The title
        author (str): The author
        published (datetime): The publication date
    book_id: int
    title: str
    author: str
    published: datetime

Note: the docstring will be used to provide documentation for swagger.

Creating the API

Now we can build the API.

from typing import Dict, List
from urllib.error import HTTPError

BOOKS: Dict[int, Book] = {}
NEXT_ID: int = 0

async def get_books() -> List[Book]:
    """Get all the books.

    This method gets all the books in the shop.

        List[Book]: All the books
    return list(BOOKS.values())

async def get_book(book_id: int) -> Book:
    """Get a book for a given id

        book_id (int): The id of the book

        HTTPError: 404, when a book is not found

        Book: The book

    if book_id not in BOOKS:
        raise HTTPError(None, 404, None, None, None)

    return BOOKS[book_id]

async def create_book(
        author: str,
        title: str,
        published: datetime
) -> int:
    """Add a book

        author (str): The author
        title (str): The title
        published (datetime): The publication date

        int: The id of the new book
    NEXT_ID += 1
    BOOKS[NEXT_ID] = Book(
    return NEXT_ID

async def update_book(
        book_id: int,
        author: str,
        title: str,
        published: datetime
) -> None:
    """Update a book

        book_id (int): The id of the book to update
        author (str): The new author
        title (str): The title
        published (datetime): The publication date

        HTTPError: 404, when a book is not found
    if book_id not in BOOKS:
        raise HTTPError(None, 404, None, None, None)
    BOOKS[book_id]['title'] = title
    BOOKS[book_id]['author'] = author
    BOOKS[book_id]['published'] = published

We can see that errors are handler by raising HTTPError from the urllib.errors standard library package. A convention has been applied such that the status code MUST appear before the message, separated by a comma.

Adding support for the REST router

Now we must create our application and add support for the router.

from bareasgi import Application
from bareasgi_rest import RestHttpRouter, add_swagger_ui

router = RestHttpRouter(
    description="A book api",
            'name': 'Books',
            'description': 'The book store API'
app = Application(http_router=router)

Note the base_path argument can be used to prefix all paths.

The RestHttpRouter is a subclass of the basic router, so all those methods are also available.

Creating the routes

Now we can create the routes:

tags = ['Books']
router.add_rest({'GET'}, '/books', get_books,tags=tags)
router.add_rest({'GET'}, '/books/{bookId:int}', get_book, tags=tags)
router.add_rest({'POST'}, '/books', create_book, tags=tags, status_code=201)
router.add_rest({'PUT'}, '/books/{bookId:int}', update_book, tags=tags, status_code=204)

First we should note that the paths will be prefixed with the base_path provided to the router.

Referring back to the implementation of get_book we can see that the camel-case path variable bookId has been mapped to the snake-case book_id parameter. The JSON object provided in the body of the create_book will similarly map camel-cased properties to the snake-cased function parameters.

We can also see how the status codes have been overridden for the POST and PUT endpoints, and all the routes have the "Books" tag for grouping in the UI.

Serving the API

Finally we can serve the API:

import uvicorn, port=9009)

Browsing to http://localhost/api/1/swagger we should see:

Top Level

When we expand GET /books/{bookId} we can see all the information provided in the docstring and typing has been passed through to the swagger UI.

GET /books/{bookId}


Thanks to rr- and contributors for the excellent docstring-parser package.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bareASGI-rest-3.2.0.tar.gz (18.4 kB view hashes)

Uploaded source

Built Distribution

bareASGI_rest-3.2.0-py3-none-any.whl (22.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page