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.8+ package.


The package can be installed from pypi.

$ pip install 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
from typing 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 bareasgi_rest import RestError

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

        RestError: 404, when a book is not found

        Book: The book

    if book_id not in BOOKS:
        raise RestError(404, "Book not found")

    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

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

We can see that errors are handler by raising ResetError. 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-4.0.1.tar.gz (18.9 kB view hashes)

Uploaded Source

Built Distribution

bareASGI_rest-4.0.1-py3-none-any.whl (22.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page