apidaora

HTTP/REST API using dataclasses and TypedDict annotation for python

Documentation: https://dutradda.github.io/apidaora

Source Code: https://github.com/dutradda/apidaora

Key Features

• Declare request objects as @jsondaora (can be TypedDict or @dataclass):

  • PathArgs for values on path
  • Query for values on query string
  • Headers for values on headers
  • Body for values on body

• Declare response objects as @jsondaora (can be TypedDict or @dataclass):

  • Headers for values on headers
  • Body for values on body

Requirements

• Python 3.7+
• jsondaora for json validation/parsing
• orjson for json/bytes serialization (jsondaora dependency)

Instalation

$ pip install apidaora

Basic example

from http import HTTPStatus
from typing import TypedDict

from jsondaora import jsondaora

from apidaora import JSONResponse, MethodType, Request, Route, asgi_app


@jsondaora
class MyQuery(TypedDict):
    name: str


@jsondaora
class MyRequest(Request):
    query: MyQuery


@jsondaora
class MyResponseBody(TypedDict):
    message: str


@jsondaora
class MyResponse(JSONResponse):
    body: MyResponseBody


def hello_controller(req: MyRequest) -> MyResponse:
    name = req.query['name']
    body = MyResponseBody(message=f'Hello {name}!')
    return MyResponse(HTTPStatus.OK, body=body)


app = asgi_app([Route('/hello', MethodType.GET, hello_controller)])

Running the server (needs uvicorn installed):

uvicorn myapp:app

INFO: Started server process [16220]
INFO: Waiting for application startup.
INFO: ASGI 'lifespan' protocol appears unsupported.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Quering the server (needs curl installed):

curl -i localhost:8000/hello?name=World

HTTP/1.1 200 OK
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 26

{"message":"Hello World!"}

Example for complete request/response

from http import HTTPStatus
from typing import TypedDict

from jsondaora import integer, jsondaora, string

from apidaora import JSONResponse, MethodType, Request, Route, asgi_app


@jsondaora
class MyPathArgs(TypedDict):
    name: str


@jsondaora
class MyQuery(TypedDict):
    location: str


@jsondaora
class MyHeaders(TypedDict):
    x_req_id: str


@jsondaora
class MyBody(TypedDict):
    last_name: str
    age: int


@jsondaora
class MyRequest(Request):
    path_args: MyPathArgs
    query: MyQuery
    headers: MyHeaders
    body: MyBody


# if the class is not a TypedDict, jsondaora
# will create a dataclass from it
@jsondaora
class You:
    name: str
    last_name: str
    location: string(max_length=100)
    age: integer(minimum=18)


@jsondaora
class MyResponseBody(TypedDict):
    hello_message: str
    about_you: You


@jsondaora
class MyResponse(JSONResponse):
    body: MyResponseBody
    headers: MyHeaders


def hello_controller(req: MyRequest) -> MyResponse:
    body = MyResponseBody(
        hello_message=hello_message(
            req.path_args['name'], req.query['location']
        ),
        about_you=You(
            name=req.path_args['name'],
            last_name=req.body['last_name'],
            location=req.query['location'],
            age=req.body['age'],
        ),
    )
    headers = MyHeaders(x_req_id=req.headers['x_req_id'])
    return MyResponse(HTTPStatus.OK, body=body, headers=headers)


def hello_message(name: str, location: str) -> str:
    return f'Hello {name}! Welcome to {location}!'


app = asgi_app([Route('/hello/{name}', MethodType.PUT, hello_controller)])

Running the server:

uvicorn myapp:app

INFO: Started server process [16220]
INFO: Waiting for application startup.
INFO: ASGI 'lifespan' protocol appears unsupported.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Quering the server:

curl -i -X PUT localhost:8000/hello/Me?location=World \
    -H 'x-req-id: 1a2b3c4d5e6f7g8h' \
    -d '{"last_name":"My Self","age":32}'

HTTP/1.1 200 OK
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
x-req-id: 1a2b3c4d5e6f7g8h
content-type: application/json
content-length: 123

{"hello_message":"Hello Me! Welcome to World!","about_you":{"name":"Me","last_name":"My Self","location":"World","age":32}}