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

Commit a3ff44b

Browse files
HomelessDinosaurHomelessDinosaur
committed
add middlewares to reference docs
1 parent 6e8c7ca commit a3ff44b

File tree

14 files changed

+521
-18
lines changed

14 files changed

+521
-18
lines changed

‎src/pages/reference/dart/api/api-all.mdx‎

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

‎src/pages/reference/dart/api/api-delete.mdx‎

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

4752
## Examples
@@ -66,6 +71,35 @@ api.delete("/customers/:customerId", (ctx) async {
6671
});
6772
```
6873

74+
### Chain services as a single method handler
75+
76+
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.
77+
78+
```dart
79+
import 'package:nitric_sdk/nitric.dart';
80+
import '../middlewares';
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+
69103
### Access the request body
70104

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

‎src/pages/reference/dart/api/api-get.mdx‎

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

4752
## Examples
@@ -62,3 +67,32 @@ api.get("/customers", (ctx) async {
6267
return ctx;
6368
});
6469
```
70+
71+
### Chain services as a single method handler
72+
73+
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.
74+
75+
```dart
76+
import 'package:nitric_sdk/nitric.dart';
77+
import '../middlewares';
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+
```

‎src/pages/reference/dart/api/api-patch.mdx‎

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

4752
## Examples
@@ -63,6 +68,35 @@ api.patch("/customers", (ctx) async {
6368
});
6469
```
6570

71+
### Chain services as a single method handler
72+
73+
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.
74+
75+
```dart
76+
import 'package:nitric_sdk/nitric.dart';
77+
import '../middlewares';
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+
66100
### Access the request body
67101

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

‎src/pages/reference/dart/api/api-post.mdx‎

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

4752
## Examples
@@ -63,6 +68,35 @@ api.post("/customers", (ctx) async {
6368
});
6469
```
6570

71+
### Chain services as a single method handler
72+
73+
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.
74+
75+
```dart
76+
import 'package:nitric_sdk/nitric.dart';
77+
import '../middlewares';
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+
66100
### Access the request body
67101

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

‎src/pages/reference/dart/api/api-put.mdx‎

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

4752
## Examples
@@ -63,6 +68,35 @@ api.put("/customers", (ctx) async {
6368
});
6469
```
6570

71+
### Chain services as a single method handler
72+
73+
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.
74+
75+
```dart
76+
import 'package:nitric_sdk/nitric.dart';
77+
import '../middlewares';
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> createOrUpdateCustomer(HttpContext ctx) async {
92+
// handle the UPDATE request...
93+
return ctx.next();
94+
}
95+
96+
// The validate middleware will run before the createOrUpdateCustomer handler
97+
Nitric.api("public").put("/customers", createOrUpdateCustomer, middlewares: [validate]);
98+
```
99+
66100
### Access the request body
67101

68102
The PUT request body is accessible from the `ctx.req` object.

0 commit comments

Comments
 (0)