apidaora
OpenAPI / 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
- Declaration of request/response as dataclasses and dicts using typing annotations
- Input data validation with jsondaora
- One of the fastest python api framework
- Can run on any asgi server
Requirements
- Python 3.8+
- jsondaora for json validation/parsing
- orjson for json/bytes serialization (jsondaora dependency)
Instalation
$ pip install apidaora
Simple example
from apidaora import appdaora, route
@route.get('/hello')
def hello_controller(name: str) -> str:
return f'Hello {name}!'
app = appdaora(hello_controller)Running the server (needs uvicorn installed):
uvicorn myapp:appINFO: 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: 14
"Hello World!"
Basic example
from typing import TypedDict
from jsondaora import IntegerField, StringField, jsondaora
from apidaora import Header, appdaora, route
class Integer(IntegerField, minimum=18):
...
class String(StringField, max_length=100):
...
class Age(Header, type=Integer):
...
@jsondaora
class You(TypedDict):
name: str
last_name: str
location: str
age: int
@jsondaora
class ReqBody(TypedDict):
last_name: str
@jsondaora
class HelloOutput(TypedDict):
hello_message: str
about_you: You
@route.put('/hello/{name}')
async def hello_controller(
name: str, location: String, age: Age, body: ReqBody
) -> HelloOutput:
you = You(
name=name,
location=location.value,
age=age.value.value,
last_name=body['last_name'],
)
return HelloOutput(
hello_message=await hello_message(name, location.value), about_you=you
)
async def hello_message(name: str, location: str) -> str:
return f'Hello {name}! Welcome to {location}!'
app = appdaora(hello_controller)Running the server:
uvicorn myapp:appINFO: 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-age: 32' \
-d '{"last_name":"My Self"}'
HTTP/1.1 200 OK
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 123
{"hello_message":"Hello Me! Welcome to World!","about_you":{"name":"Me","location":"World","age":32,"last_name":"My Self"}}
Example for more request/response details
from http import HTTPStatus
from typing import Dict
from jsondaora import jsondaora
from apidaora import BadRequestError, Header, Response, appdaora, json, route
# Domain layer, here are the domain related definitions
# it is apidaora/framework/http independent
@jsondaora
class You:
name: str
last_name: str
age: int
DB: Dict[str, You] = {}
def add_you(you: You) -> None:
if you.name in DB:
raise YouAlreadyBeenAddedError(you.name)
DB[you.name] = you
def get_you(name: str) -> You:
try:
return DB[name]
except KeyError:
raise YouWereNotFoundError(name)
class DBError(Exception):
@property
def info(self) -> Dict[str, str]:
return {'name': self.args[0]}
class YouAlreadyBeenAddedError(DBError):
name = 'you-already-been-added'
class YouWereNotFoundError(DBError):
name = 'you-were-not-found'
# Application layer, here are the http related definitions
# See: https://dutrdda.github.io/apidaora/tutorial/headers/
class ReqID(Header, type=str, http_name='http_req_id'):
...
@route.post('/you/')
async def add_you_controller(req_id: ReqID, body: You) -> Response:
try:
add_you(body)
except YouAlreadyBeenAddedError as error:
raise BadRequestError(name=error.name, info=error.info) from error
return json(body, HTTPStatus.CREATED, headers=(req_id,))
@route.get('/you/{name}')
async def get_you_controller(name: str, req_id: ReqID) -> Response:
try:
return json(get_you(name), headers=(req_id,))
except YouWereNotFoundError as error:
raise BadRequestError(name=error.name, info=error.info) from error
app = appdaora([add_you_controller, get_you_controller])Running the server:
uvicorn myapp:appINFO: 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 -X POST -i localhost:8000/you/ -H 'http_req_id: 1a2b3c4d' -d '{"name":"Me","last_name":"Myself","age":32}'
HTTP/1.1 201 Created
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 43
http_req_id: 1a2b3c4d
{"name":"Me","last_name":"Myself","age":32}
curl -i localhost:8000/you/Me -H 'http_req_id: 4d3c2b1a'
HTTP/1.1 200 OK
date: Thu, 1st January 1970 00:00:00 GMT
server: uvicorn
content-type: application/json
content-length: 43
http_req_id: 4d3c2b1a
{"name":"Me","last_name":"Myself","age":32}
Benchmark
The full results can be found here
