swadhin / justapi public

p3b: add JustAPIApp API reference — full parameter docs for all methods

swadhinbiswas committed 3 months ago

ddf0c91

1 parent 70f3afd

commit ddf0c91

1 file changed

+154 -0

Files

docs_site

src

content

docs

api-reference

justapiapp.md +154

Showing 1 changed file+154-0

docs_site/src/content/docs/api-reference/justapiapp.md

▼docs_site/src/content/docs/api-reference/justapiapp.md

+154-0

@@ -0,0 +1,154 @@
	1	+---
	2	+title: JustAPIApp
	3	+description: The core application class — register routes, middleware, plugins, and run the server.
	4	+---
	5	+
	6	+`JustAPIApp` is the central class of any JustAPI application. It manages route registration, middleware chains, plugin lifecycle, database connections, and server startup.
	7	+
	8	+## Constructor
	9	+
	10	+```python
	11	+from justapi import JustAPIApp
	12	+
	13	+app = JustAPIApp(
	14	+ title="My API",
	15	+ version="1.0.0",
	16	+ description="A high-performance API powered by JustAPI",
	17	+)
	18	+```
	19	+
	20	+### Parameters
	21	+
	22	+\| Parameter \| Type \| Default \| Description \|
	23	+\|---\|---\|---\|---\|
	24	+\| `title` \| `str` \| `"JustAPI"` \| API title for OpenAPI docs \|
	25	+\| `version` \| `str` \| `"1.0.0"` \| API version for OpenAPI docs \|
	26	+\| `description` \| `str` \| `""` \| API description for OpenAPI docs \|
	27	+
	28	+## Route Registration
	29	+
	30	+\| Method \| Returns \| Description \|
	31	+\|---\|---\|---\|
	32	+\| `get(path, dependencies, tags)` \| decorator \| Register GET route \|
	33	+\| `post(path, body_schema, schema, dependencies, tags, native)` \| decorator \| Register POST route \|
	34	+\| `put(path, body_schema, schema, dependencies, tags, native)` \| decorator \| Register PUT route \|
	35	+\| `patch(path, body_schema, schema, dependencies, tags, native)` \| decorator \| Register PATCH route \|
	36	+\| `delete(path, dependencies, tags)` \| decorator \| Register DELETE route \|
	37	+\| `websocket(path)` \| decorator \| Register WebSocket handler \|
	38	+\| `include_router(router, prefix)` \| `None` \| Include routes from APIRouter \|
	39	+
	40	+### Route Parameter Details
	41	+
	42	+\| Parameter \| Type \| Default \| Description \|
	43	+\|---\|---\|---\|---\|
	44	+\| `path` \| `str` \| required \| URL path template (e.g., `/items/{id}`) \|
	45	+\| `body_schema` \| `Schema` subclass \| `None` \| Schema for request body validation in Rust \|
	46	+\| `schema` \| `Schema` subclass \| `None` \| Alias for `body_schema` \|
	47	+\| `dependencies` \| `list[Depends]` \| `None` \| Route-level dependencies \|
	48	+\| `tags` \| `list[str]` \| `None` \| OpenAPI tags \|
	49	+\| `native` \| `bool` \| `False` \| Execute entirely in Rust (724k+ RPS) \|
	50	+
	51	+## Middleware & Security
	52	+
	53	+\| Method \| Description \|
	54	+\|---\|---\|
	55	+\| `middleware(type)` \| Decorator to register HTTP middleware (`"http"`) \|
	56	+\| `add_cors(allow_origins, allow_methods, allow_headers, allow_credentials)` \| Configure CORS \|
	57	+\| `enable_secure_headers(with_hsts)` \| Add security headers \|
	58	+\| `add_middleware(middleware_cls, **kwargs)` \| Add middleware class (Starlette parity) \|
	59	+
	60	+## Resilience
	61	+
	62	+\| Method \| Description \|
	63	+\|---\|---\|
	64	+\| `enable_circuit_breaker(failure_threshold, reset_timeout_ms)` \| Enable circuit breaker pattern \|
	65	+\| `enable_request_coalescing(headers)` \| Deduplicate concurrent identical requests \|
	66	+
	67	+## Database
	68	+
	69	+\| Method \| Description \|
	70	+\|---\|---\|
	71	+\| `set_database(url, init_sql, max_connections, request_acquire_timeout, wal, pragmas)` \| Configure database connection pool \|
	72	+
	73	+## Plugins
	74	+
	75	+\| Method \| Description \|
	76	+\|---\|---\|
	77	+\| `use(plugin)` \| Register a plugin (calls `build()`, `on_startup()`, `on_shutdown()`) \|
	78	+
	79	+## Agent System
	80	+
	81	+\| Method \| Description \|
	82	+\|---\|---\|
	83	+\| `tool` \| Decorator to register an MCP tool \|
	84	+\| `stream_json(path, schema, mode)` \| Decorator for validated JSON streaming \|
	85	+\| `enable_sessions()` \| Enable Rust-backed agent session store \|
	86	+\| `enable_system_routes()` \| Enable `/_system/tools` and `/_system/tools/call` \|
	87	+\| `run_mcp_stdio()` \| Run MCP stdio server \|
	88	+
	89	+## Observability
	90	+
	91	+\| Method \| Description \|
	92	+\|---\|---\|
	93	+\| `register_health_check(name, callable)` \| Register a custom health check \|
	94	+
	95	+## Server Startup
	96	+
	97	+```python
	98	+app.run(
	99	+ addr="127.0.0.1:8000",
	100	+ max_body_size=50 * 1024 * 1024, # 50 MiB
	101	+)
	102	+```
	103	+
	104	+\| Parameter \| Type \| Default \| Description \|
	105	+\|---\|---\|---\|---\|
	106	+\| `addr` \| `str` \| `"127.0.0.1:8000"` \| Bind address \|
	107	+\| `max_body_size` \| `int` \| `52428800` \| Max request body size (bytes) \|
	108	+
	109	+## Multi-Protocol
	110	+
	111	+\| Method \| Description \|
	112	+\|---\|---\|
	113	+\| `graphql(path)` \| Mount GraphQL endpoint with GraphiQL UI \|
	114	+
	115	+## Exception Handlers
	116	+
	117	+\| Method \| Description \|
	118	+\|---\|---\|
	119	+\| `exception_handler(exc_class)` \| Decorator to register custom exception handler \|
	120	+
	121	+## Example: Full Configuration
	122	+
	123	+```python
	124	+from justapi import JustAPIApp, Depends, HTTPException, Schema
	125	+from pydantic import Field
	126	+
	127	+app = JustAPIApp(
	128	+ title="Enterprise API",
	129	+ version="2.0.0",
	130	+ description="Production-grade API with all features",
	131	+)
	132	+
	133	+# Database
	134	+app.set_database("postgres://localhost/mydb")
	135	+
	136	+# Security
	137	+app.add_cors(allow_origins=["https://app.example.com"])
	138	+app.enable_secure_headers(with_hsts=True)
	139	+
	140	+# Resilience
	141	+app.enable_circuit_breaker(failure_threshold=5, reset_timeout_ms=30000)
	142	+
	143	+# Agent
	144	+app.enable_sessions()
	145	+app.enable_system_routes()
	146	+
	147	+# Routes
	148	+@app.get("/")
	149	+def root(request):
	150	+ return {"status": "ok"}
	151	+
	152	+if __name__ == "__main__":
	153	+ app.run("0.0.0.0:8080", max_body_size=1024 * 1024)
	154	+```
0	155