Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Commit 463511a

Browse files
HomelessDinosaurdavemooreuws
HomelessDinosaur
and
davemooreuws
authored
docs: add dart middleware to api docs (#599)
Co-authored-by: David Moore <[email protected]>
1 parent da3837f commit 463511a

16 files changed

+548
-21
lines changed

‎docs/apis.mdx‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -674,7 +674,16 @@ func validate(next apis.Handler) apis.Handler {
674674
```
675675

676676
```dart !!
677-
// Middleware currently not supported in dart
677+
Future<HttpContext> validate(HttpContext ctx) async {
678+
if (!ctx.req.headers.containsKey("Content-Type")) {
679+
ctx.res.status = 400;
680+
ctx.res.body = "header Content-Type is required";
681+
682+
return ctx;
683+
}
684+
685+
return ctx.next();
686+
}
678687
```
679688

680689
</CodeSwitcher>
@@ -742,7 +751,15 @@ func main() {
742751
```
743752

744753
```dart !!
745-
// API level middleware currently not supported in dart
754+
import 'package:nitric_sdk/nitric.dart';
755+
import '../middlewares';
756+
757+
final customersApi = Nitric.api(
758+
"customers",
759+
opts: ApiOptions(
760+
middlewares: [logRequest, validate],
761+
)
762+
);
746763
```
747764

748765
</CodeSwitcher>
@@ -819,7 +836,21 @@ func main() {
819836
```
820837

821838
```dart !!
822-
// Route level middleware currently not supported in dart
839+
import 'package:nitric_sdk/nitric.dart';
840+
import '../middlewares';
841+
842+
Future<HttpContext> getAllCustomers(HttpContext ctx) async {
843+
// gets the customers
844+
return ctx.next();
845+
}
846+
847+
final customersApi = Nitric.api("customers");
848+
849+
// Inline using .get()
850+
customersApi.get("/customers", getAllCustomers, middlewares: [logRequest, validate]);
851+
852+
// Inline using .route()
853+
customersApi.route("/customers", middlewares: [logRequest, validate]).get(getAllCustomers);
823854
```
824855

825856
</CodeSwitcher>

‎docs/reference/dart/api/api-all.mdx‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
description: "Reference for Nitric's Dart library - Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on the route."
3+
---
4+
5+
# Dart - api.all()
6+
7+
Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on a route.
8+
9+
<Note>
10+
This method is a convenient short version of
11+
[api().route().all()](./api-route-all)
12+
</Note>
13+
14+
```dart
15+
import 'package:nitric_sdk/nitric.dart';
16+
17+
// Create an API named 'public'
18+
final api = Nitric.api("public");
19+
20+
api.all("/customers/:customersId", (ctx) async {
21+
// construct a response for all incoming HTTP requests
22+
final responseBody = {};
23+
ctx.res.json(responseBody);
24+
25+
return ctx;
26+
});
27+
```
28+
29+
## Parameters
30+
31+
<Properties>
32+
<Property name="match" required type="String">
33+
The path matcher to use for the route. Matchers accept path parameters in
34+
the form of a colon prefixed string. The string provided will be used as
35+
that path parameter's name when calling handlers.
36+
</Property>
37+
<Property name="handler" required type="HttpHandler">
38+
The middleware service to use as the handler for HTTP requests.
39+
</Property>
40+
<Property name="security" type="List<OidcOptions>">
41+
Security rules to apply with scopes to the entire API.
42+
</Property>
43+
<Property name="middlewares" type="List<HttpHandler>">
44+
The list of middleware that will run before the handler is called. To call
45+
the next middleware in the chain use `ctx.next()`, to finish early return
46+
`ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
47+
</Property>
48+
</Properties>
49+
50+
## Examples
51+
52+
### Register a handler for all requests
53+
54+
```dart
55+
import 'package:nitric_sdk/nitric.dart';
56+
57+
// Create an API named 'public'
58+
final api = Nitric.api("public");
59+
60+
api.all("/customers/:customersId", (ctx) async {
61+
// construct a response for all incoming HTTP requests
62+
final responseBody = {};
63+
ctx.res.json(responseBody);
64+
65+
return ctx;
66+
});
67+
```
68+
69+
### Chain services as a single method handler
70+
71+
When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
72+
73+
```dart
74+
import 'package:nitric_sdk/nitric.dart';
75+
import '../middlewares';
76+
77+
Future<HttpContext> validate(HttpContext ctx) async {
78+
if (!ctx.req.headers.containsKey("Content-Type")) {
79+
ctx.res.status = 400;
80+
ctx.res.body = "header Content-Type is required";
81+
82+
// End the middleware chain by not calling `ctx.next()`.
83+
return ctx;
84+
}
85+
86+
return ctx.next();
87+
}
88+
89+
Future<HttpContext> handleCustomer(HttpContext ctx) async {
90+
// handle the request...
91+
return ctx.next();
92+
}
93+
94+
// The validate middleware will run before the handleCustomer handler
95+
Nitric.api("public").all("/customers", handleCustomer, middlewares: [validate]);
96+
```
97+
98+
### Access the request body
99+
100+
The request body is accessible from the `ctx.req` object.
101+
102+
```dart
103+
import 'package:nitric_sdk/nitric.dart';
104+
105+
// Create an API named 'public'
106+
final api = Nitric.api("public");
107+
108+
api.all("/customers/:customerId", (ctx) async {
109+
// Extract the path parameter
110+
final id = ctx.req.pathParams["customerId"]!;
111+
112+
// Extract the request body
113+
final body = ctx.req.json();
114+
115+
// Construct response for the /customers request...
116+
final responseBody = {};
117+
ctx.res.json(responseBody);
118+
119+
return ctx;
120+
});
121+
```

‎docs/reference/dart/api/api-delete.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ api.delete("/customers/:customerId", (ctx) async {
4343
<Property name="security" type="List<OidcOptions>">
4444
Security rules to apply with scopes to the entire API.
4545
</Property>
46+
<Property name="middlewares" type="List<HttpHandler>">
47+
The list of middleware that will run before the handler is called. To call
48+
the next middleware in the chain use `ctx.next()`, to finish early return
49+
`ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
50+
</Property>
4651
</Properties>
4752

4853
## Examples
@@ -67,6 +72,34 @@ api.delete("/customers/:customerId", (ctx) async {
6772
});
6873
```
6974

75+
### Chain services as a single method handler
76+
77+
When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
78+
79+
```dart
80+
import 'package:nitric_sdk/nitric.dart';
81+
82+
Future<HttpContext> validate(HttpContext ctx) async {
83+
if (!ctx.req.headers.containsKey("Content-Type")) {
84+
ctx.res.status = 400;
85+
ctx.res.body = "header Content-Type is required";
86+
87+
// End the middleware chain by not calling `ctx.next()`.
88+
return ctx;
89+
}
90+
91+
return ctx.next();
92+
}
93+
94+
Future<HttpContext> deleteCustomer(HttpContext ctx) async {
95+
// handle the DELETE request...
96+
return ctx.next();
97+
}
98+
99+
// The validate middleware will run before the deleteCustomer handler
100+
Nitric.api("public").delete("/customers", deleteCustomer, middlewares: [validate]);
101+
```
102+
70103
### Access the request body
71104

72105
The DELETE request body is accessible from the `ctx.req` object.

‎docs/reference/dart/api/api-get.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ api.get("/customers/:customerId", (ctx) async {
4343
<Property name="security" type="List<OidcOptions>">
4444
Security rules to apply with scopes to the entire API.
4545
</Property>
46+
<Property name="middlewares" type="List<HttpHandler>">
47+
The list of middleware that will run before the handler is called. To call
48+
the next middleware in the chain use `ctx.next()`, to finish early return
49+
`ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
50+
</Property>
4651
</Properties>
4752

4853
## Examples
@@ -63,3 +68,31 @@ api.get("/customers", (ctx) async {
6368
return ctx;
6469
});
6570
```
71+
72+
### Chain services as a single method handler
73+
74+
When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
75+
76+
```dart
77+
import 'package:nitric_sdk/nitric.dart';
78+
79+
Future<HttpContext> validate(HttpContext ctx) async {
80+
if (!ctx.req.headers.containsKey("Content-Type")) {
81+
ctx.res.status = 400;
82+
ctx.res.body = "header Content-Type is required";
83+
84+
// End the middleware chain by not calling `ctx.next()`.
85+
return ctx;
86+
}
87+
88+
return ctx.next();
89+
}
90+
91+
Future<HttpContext> getCustomer(HttpContext ctx) async {
92+
// handle the GET request...
93+
return ctx.next();
94+
}
95+
96+
// The validate middleware will run before the getCustomer handler
97+
Nitric.api("public").get("/customers", getCustomer, middlewares: [validate]);
98+
```

‎docs/reference/dart/api/api-patch.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ api.patch("/customers/:customerId", (ctx) async {
4343
<Property name="security" type="List<OidcOptions>">
4444
Security rules to apply with scopes to the entire API.
4545
</Property>
46+
<Property name="middlewares" type="List<HttpHandler>">
47+
The list of middleware that will run before the handler is called. To call
48+
the next middleware in the chain use `ctx.next()`, to finish early return
49+
`ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
50+
</Property>
4651
</Properties>
4752

4853
## Examples
@@ -64,6 +69,34 @@ api.patch("/customers", (ctx) async {
6469
});
6570
```
6671

72+
### Chain services as a single method handler
73+
74+
When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
75+
76+
```dart
77+
import 'package:nitric_sdk/nitric.dart';
78+
79+
Future<HttpContext> validate(HttpContext ctx) async {
80+
if (!ctx.req.headers.containsKey("Content-Type")) {
81+
ctx.res.status = 400;
82+
ctx.res.body = "header Content-Type is required";
83+
84+
// End the middleware chain by not calling `ctx.next()`.
85+
return ctx;
86+
}
87+
88+
return ctx.next();
89+
}
90+
91+
Future<HttpContext> udpateCustomer(HttpContext ctx) async {
92+
// handle the PATCH request...
93+
return ctx.next();
94+
}
95+
96+
// The validate middleware will run before the updateCustomer handler
97+
Nitric.api("public").patch("/customers", updateCustomer, middlewares: [validate]);
98+
```
99+
67100
### Access the request body
68101

69102
The PATCH request body is accessible from the `ctx.req` object.

‎docs/reference/dart/api/api-post.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ api.post("/customers/:customerId", (ctx) async {
4343
<Property name="security" type="List<OidcOptions>">
4444
Security rules to apply with scopes to the entire API.
4545
</Property>
46+
<Property name="middlewares" type="List<HttpHandler>">
47+
The list of middleware that will run before the handler is called. To call
48+
the next middleware in the chain use `ctx.next()`, to finish early return
49+
`ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
50+
</Property>
4651
</Properties>
4752

4853
## Examples
@@ -64,6 +69,34 @@ api.post("/customers", (ctx) async {
6469
});
6570
```
6671

72+
### Chain services as a single method handler
73+
74+
When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
75+
76+
```dart
77+
import 'package:nitric_sdk/nitric.dart';
78+
79+
Future<HttpContext> validate(HttpContext ctx) async {
80+
if (!ctx.req.headers.containsKey("Content-Type")) {
81+
ctx.res.status = 400;
82+
ctx.res.body = "header Content-Type is required";
83+
84+
// End the middleware chain by not calling `ctx.next()`.
85+
return ctx;
86+
}
87+
88+
return ctx.next();
89+
}
90+
91+
Future<HttpContext> createCustomer(HttpContext ctx) async {
92+
// handle the POST request...
93+
return ctx.next();
94+
}
95+
96+
// The validate middleware will run before the createCustomer handler
97+
Nitric.api("public").post("/customers", createCustomer, middlewares: [validate]);
98+
```
99+
67100
### Access the request body
68101

69102
The POST request body is accessible from the `ctx.req` object.

0 commit comments

Comments
 (0)