swadhin / justapi public

p1c: enhance First Steps — expected output, curl tests, comparison table, next steps

swadhinbiswas committed 3 months ago
95b0cc4
1 parent 8551f90
commit 95b0cc4
1 file changed
+76 -6
Showing 1 changed file+76-6
docs_site/src/content/docs/getting-started/first-steps.md
▼docs_site/src/content/docs/getting-started/first-steps.md
+76-6
@@ -3,6 +3,8 @@ title: First Steps with JustAPI
3
3
description: Create your first API endpoint in under 2 minutes.
4
4
---
5
5
6
+This guide walks you through building and running your first JustAPI application from scratch.
7
+
6
8
## 1. Create a `main.py` File
7
9
8
10
```python
@@ -10,15 +12,24 @@ from justapi import JustAPIApp
10
12
11
13
app = JustAPIApp(title="My First App", version="1.0.0")
12
14
15
+
13
16
@app.get("/")
14
17
def read_root(request):
15
18
return {"status": "ok", "message": "Welcome to JustAPI!"}
16
19
20
+
17
21
@app.get("/users/{user_id}")
18
22
def read_user(request, user_id: int):
19
23
return {"user_id": user_id, "active": True}
20
24
```
21
25
26
+### What's happening here?
27
+
28
+- `JustAPIApp()` initializes the Rust runtime — no separate server process needed
29
+- `@app.get("/")` registers a route in the Rust radix-trie router (matchit)
30
+- The `request` parameter is a zero-copy view into the HTTP request (no serialization overhead)
31
+- Return a dict — JustAPI serializes it to JSON via `serde_json` in Rust
32
+
22
33
## 2. Run the Application
23
34
24
35
Run directly using Python:
@@ -27,16 +38,75 @@ Run directly using Python:
27
38
python main.py
28
39
```
29
40
41
+You should see output similar to:
42
+
43
+```
44
+[Rust Tokio Runtime] Listening on 127.0.0.1:8000
45
+[Rust Tokio Runtime] Worker threads: 12
46
+[Rust Tokio Runtime] OpenAPI docs at http://127.0.0.1:8000/docs
47
+```
48
+
30
49
Or run using the hot-reloading dev server:
31
50
32
51
```bash
33
52
justapi serve --reload
34
53
```
35
54
36
-## 3. Explore Interactive Documentation
55
+## 3. Test the API
56
+
57
+Open a new terminal and test with `curl`:
58
+
59
+```bash
60
+curl http://127.0.0.1:8000/
61
+# Output: {"status":"ok","message":"Welcome to JustAPI!"}
62
+
63
+curl http://127.0.0.1:8000/users/42
64
+# Output: {"user_id":42,"active":true}
65
+
66
+curl http://127.0.0.1:8000/users/abc
67
+# Output: {"detail":"validation error"}
68
+```
69
+
70
+Notice the third request returns a **422 validation error** automatically — the Rust router rejected the non-integer `user_id` without ever calling Python.
71
+
72
+## 4. Explore Interactive Documentation
73
+
74
+JustAPI auto-generates OpenAPI 3.1 documentation. Open your browser to:
75
+
76
+| URL | Description |
77
+|---|---|
78
+| `http://127.0.0.1:8000/docs` | **Swagger UI** — Interactive API explorer |
79
+| `http://127.0.0.1:8000/redoc` | **ReDoc** — Alternative documentation viewer |
80
+| `http://127.0.0.1:8000/scalar` | **Scalar UI** — Modern API client |
81
+| `http://127.0.0.1:8000/openapi.json` | Raw OpenAPI 3.1 spec |
82
+
83
+## 5. Add a POST Endpoint
84
+
85
+```python
86
+from pydantic import BaseModel
87
+
88
+class Item(BaseModel):
89
+ name: str
90
+ price: float
91
+ is_offer: bool = None
92
+
93
+@app.post("/items/")
94
+def create_item(request, item: Item):
95
+ return {"name": item.name, "price": item.price}
96
+```
97
+
98
+## What JustAPI Does Differently
99
+
100
+| Aspect | Other Frameworks | JustAPI |
101
+|---|---|---|
102
+| **Route matching** | Python dict iteration | Rust radix trie (O(1)) |
103
+| **JSON parsing** | Python `json.loads()` | Rust `serde_json` (GIL released) |
104
+| **Validation** | Python runtime | Rust `jsonschema-rs` (GIL released) |
105
+| **Response body** | Python bytes | Rust zero-copy buffer |
106
+| **Concurrency** | GIL-bound async | True parallel via `py.allow_threads` |
107
+
108
+## Next Steps
37
109
38
-Open your browser to:
39
-* **Swagger UI:** `http://127.0.0.1:8000/docs`
40
-* **ReDoc:** `http://127.0.0.1:8000/redoc`
41
-* **Scalar UI:** `http://127.0.0.1:8000/scalar`
42
-* **OpenAPI Spec:** `http://127.0.0.1:8000/openapi.json`
110
+- [Path & Query Parameters](/tutorials/path-query-params/) — Deep dive into routing
111
+- [Request Body & Validation](/tutorials/request-body/) — Schema validation with Pydantic
112
+- [CLI Project Scaffolder](/getting-started/cli-scaffolder/) — Generate complete project templates
43
113