update docs to add examples

README.md

@@ -7,7 +7,7 @@
 [![PyPi](https://img.shields.io/pypi/v/arrest.svg)](https://pypi.python.org/pypi/arrest)
 
 - Documentation: https://s-bose.github.io/arrest/
-
+0.30.6
 Enable data validation for REST APIs.
 
 Arrest provides an easy and declarative way of defining, managing, and calling RESTful HTTP APIs with type validation, retries, exception handling, and other batteries included.
@@ -21,18 +21,12 @@ Arrest lets you define your RESTful API services in a simple encapsulation that
 6. Callbacks
 7. Automatic code generation from OpenAPI Schema
 
-Here is an example of a typical client-side functions for interacting with an HTTP Service.
-![](./docs/assets/screenshot_httpx.png)
-
-And here is the same functionality achieved using Arrest.
-![](./docs/assets/screenshot_arrest.png)
-
-
 ## Contents
 
 1. [Installation](#installation)
 2. [Getting Started](#getting-started)
-3. [Contributing](#contributing)
+3. [Examples](#examples)
+4. [Contributing](#contributing)
 
 ## Installation
 
@@ -53,6 +47,9 @@ uv add arrest
 
 ## Getting Started
 
+Assuming you already have arrest installed in your system, let us create a simple connection.
+We have a REST endpoint `htthttps://www.xyz-service.default.local.cluster/api/v1` which has a resource `/users` with method `GET`.
+
 ```python
 import logging
 from arrest import Resource, Service
@@ -80,7 +77,68 @@ except ArrestHTTPException as exc:
     logging.warning(f"{exc.status_code} {exc.data}")
 ```
 
-##
+This will make an HTTP GET request to `https://www.xyz-service.default.local.cluster/api/v1/users/123`.
+
+You can also provide a request type for your handlers. This can be done by passing a third entry to your handler tuple containing the pydantic class, or pass it directly to the handler dict or `ResourceHandler` initialization.
+
+```python
+from pydantic import BaseModel
+
+class UserRequest(BaseModel):
+    name: str
+    email: str
+    password: str
+    role: str
+
+Resource(
+    route="/users,
+    handlers=[
+        ("POST", "/", UserRequest) # or ResourceHandler(method="POST", route="/", request=UserRequest)
+                                   # or {"method": "POST", "route": "/", "request": UserRequest}
+    ]
+)
+
+await service.users.post("/", request={
+    "name": "John Doe",
+    "email": "[email protected]",
+    "password": "secret",
+    "role": "admin"
+    }
+)
+```
+
+This gets automatically validated and parsed as `UserRequest` before sending the request payload to the server. If any validation error is raised the request won't go.
+
+
+Similar to request, you can pass an additional fourth argument in the handler tuple for specifying a pydantic model for the handler.
+If provided it will automatically deserialize the returned success json response into either a model instance or a list of model instances.
+
+
+## Examples
+
+```python
+class UserResponse(BaseModel):
+    name: str
+    email: str
+    role: str
+    created_at: datetime
+    updated_at: datetime
+    is_deleted: bool
+
+Resource(
+    route="/user",
+    handlers=[
+        ("GET", "/{user_id}", None, UserResponse), # if no request type to be supplied, leave it as `None`
+    ]
+)
+
+user_id = "123"
+response = await svc.user.get(f"/{user_id}") # type: UserResponse
+```
+
+Here, the JSON response from `https://www.xyz-service.default.local.cluster/api/v1/users/123` will be deserialized into `UserResponse` model instance.
+
+For more info, please check the [docs](https://s-bose.github.io/arrest/getting-started)
 
 
 ## Contributing

docs/examples.md

@@ -0,0 +1,28 @@
+You can refer to the `example` folder for different use cases.
+
+It comes with a completely functional REST API suite for task management with CRUD operations for `users` and `tasks`.
+
+It uses in-memory dictionaries for data storage, so of course this is just for testing and learning purposes.
+
+It comes with a set of test files which test compatibility with 3 different types.
+
+1. Pydantic BaseModel
+2. Python dataclasses
+3. No class, rely on dicts and lists
+
+## Packages Used
+
+1. [FastAPI==0.112.2](https://fastapi.tiangolo.com)
+2. [Pydantic==2.8.2](https://docs.pydantic.dev/latest/)
+3. [Uvicorn==0.30.6](https://www.uvicorn.org/)
+
+## Installation
+
+To run the example FastAPI application, simply go to the example directory at the project root, and run `bash run.sh`, and you shoule be able to access the Swagger docs at [http://localhost:8080/docs]()
+
+Alternatively, you can set up your own virtualenv, and install the `requirements.example.txt` and run `uvicorn app.main:app`.
+
+
+## Running Tests
+
+Create a virtualenv that contains the dependencies in the example directory, and run `pytest -vvv`.

mkdocs.yml

@@ -34,6 +34,7 @@ nav:
   - Introduction: index.md
   - Getting Started:
     - getting-started.md
+    - Examples: examples.md
     - Configuring your request: configuring-request.md
     - Resources and Services: resources-services.md
   - OpenAPI Integration: openapi.md