cinderblock-json-api 0.1.0

JSON REST API extension for cinderblock with Axum router, auto-registered endpoints, and OpenAPI support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# Cinderblock

A declarative, resource-oriented application framework for Rust.

Define your domain model once using the `resource!` macro and Cinderblock generates the struct, CRUD operations, persistence layer, and REST API endpoints.

## Quick Example

```rust
use cinderblock_core::{Context, resource, serde::{Deserialize, Serialize}};
use uuid::Uuid;

resource! {
    name = Helpdesk.Support.Ticket;

    attributes {
        ticket_id Uuid {
            primary_key true;
            writable false;
            default || uuid::Uuid::new_v4();
        }
        subject String;
        status TicketStatus;
    }

    actions {
        create open;
        create assign { accept [subject]; };
        update close {
            accept [];
            change_ref |ticket| {
                ticket.status = TicketStatus::Closed;
            };
        };
        destroy remove;
    }

    extensions {
        cinderblock_json_api {};
        cinderblock_sqlx { table = "tickets"; };
    }
}
```

This single declaration generates:

- A `Ticket` struct with serialization
- Typed action markers (`Open`, `Assign`, `Close`, `Remove`) with dedicated input structs
- `Create`, `Update`, and `Destroy` trait implementations
- REST API endpoints via Axum with OpenAPI documentation
- SQL persistence via SQLx with parameterized queries

## Key Concepts

### Named Actions

Actions are not generic CRUD verbs -- they are domain-specific operations with their own types and input validation:

```rust
cinderblock_core::create::<Ticket, Open>(open_input, &ctx).await?;
cinderblock_core::update::<Ticket, Close>(&ticket_id, close_input, &ctx).await?;
cinderblock_core::destroy::<Ticket, Remove>(&ticket_id, &ctx).await?;
```

Actions can restrict which fields they accept (`accept [field1, field2]`) and apply programmatic mutations via `change_ref` closures.

### Pluggable Data Layers

- **InMemoryDataLayer** (default) -- global `RwLock<HashMap>` for prototyping
- **SqliteDataLayer** (via `cinderblock-sqlx`) -- full SQLite persistence using SQLx

### Extension System

Extensions hook into the `resource!` macro to generate additional code:

```rust
extensions {
    cinderblock_json_api {};                    // REST API with OpenAPI
    cinderblock_sqlx { table = "my_table"; };   // SQL persistence
}
```

## Crates

| Crate | Description |
|---|---|
| `cinderblock-core` | Resource trait, CRUD functions, Context, in-memory data layer |
| `cinderblock-core-macros` | The `resource!` proc macro |
| `cinderblock-extension-api` | Shared DSL parser types for extension authors |
| `cinderblock-json-api` | JSON REST API extension (Axum router, OpenAPI, Swagger UI) |
| `cinderblock-json-api-macros` | JSON API extension proc macro |
| `cinderblock-sqlx` | SQLx data layer extension (SQLite) |
| `cinderblock-sqlx-macros` | SQLx extension proc macro |

## Running the Examples

```sh
# Core CRUD with in-memory storage
cargo run --example helpdesk -p cinderblock-core

# JSON API server with Swagger UI
cargo run --example helpdesk_api -p cinderblock-json-api --features swagger-ui
```

The API example starts a server on `http://localhost:3000` with endpoints like:

```
GET    /helpdesk/support/ticket
POST   /helpdesk/support/ticket/open
PATCH  /helpdesk/support/ticket/{id}/close
DELETE /helpdesk/support/ticket/{id}/remove
GET    /openapi.json
```

## Status

Early development (0.1.0). The API is not stable.

## License

Licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).