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

Commit 1d29f28

Browse files
HomelessDinosaurHomelessDinosaur
committed
add middlewares to reference docs
1 parent 3946eaa commit 1d29f28

File tree

14 files changed

+521
-18
lines changed

14 files changed

+521
-18
lines changed

‎docs/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+
```

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

Lines changed: 34 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,35 @@ 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+
import '../middlewares';
82+
83+
Future<HttpContext> validate(HttpContext ctx) async {
84+
if (!ctx.req.headers.containsKey("Content-Type")) {
85+
ctx.res.status = 400;
86+
ctx.res.body = "header Content-Type is required";
87+
88+
// End the middleware chain by not calling `ctx.next()`.
89+
return ctx;
90+
}
91+
92+
return ctx.next();
93+
}
94+
95+
Future<HttpContext> deleteCustomer(HttpContext ctx) async {
96+
// handle the DELETE request...
97+
return ctx.next();
98+
}
99+
100+
// The validate middleware will run before the deleteCustomer handler
101+
Nitric.api("public").delete("/customers", deleteCustomer, middlewares: [validate]);
102+
```
103+
70104
### Access the request body
71105

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

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

Lines changed: 34 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,32 @@ 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+
import '../middlewares';
79+
80+
Future<HttpContext> validate(HttpContext ctx) async {
81+
if (!ctx.req.headers.containsKey("Content-Type")) {
82+
ctx.res.status = 400;
83+
ctx.res.body = "header Content-Type is required";
84+
85+
// End the middleware chain by not calling `ctx.next()`.
86+
return ctx;
87+
}
88+
89+
return ctx.next();
90+
}
91+
92+
Future<HttpContext> getCustomer(HttpContext ctx) async {
93+
// handle the GET request...
94+
return ctx.next();
95+
}
96+
97+
// The validate middleware will run before the getCustomer handler
98+
Nitric.api("public").get("/customers", getCustomer, middlewares: [validate]);
99+
```

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

Lines changed: 34 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,35 @@ 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+
import '../middlewares';
79+
80+
Future<HttpContext> validate(HttpContext ctx) async {
81+
if (!ctx.req.headers.containsKey("Content-Type")) {
82+
ctx.res.status = 400;
83+
ctx.res.body = "header Content-Type is required";
84+
85+
// End the middleware chain by not calling `ctx.next()`.
86+
return ctx;
87+
}
88+
89+
return ctx.next();
90+
}
91+
92+
Future<HttpContext> udpateCustomer(HttpContext ctx) async {
93+
// handle the PATCH request...
94+
return ctx.next();
95+
}
96+
97+
// The validate middleware will run before the updateCustomer handler
98+
Nitric.api("public").patch("/customers", updateCustomer, middlewares: [validate]);
99+
```
100+
67101
### Access the request body
68102

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

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

Lines changed: 34 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,35 @@ 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+
import '../middlewares';
79+
80+
Future<HttpContext> validate(HttpContext ctx) async {
81+
if (!ctx.req.headers.containsKey("Content-Type")) {
82+
ctx.res.status = 400;
83+
ctx.res.body = "header Content-Type is required";
84+
85+
// End the middleware chain by not calling `ctx.next()`.
86+
return ctx;
87+
}
88+
89+
return ctx.next();
90+
}
91+
92+
Future<HttpContext> createCustomer(HttpContext ctx) async {
93+
// handle the POST request...
94+
return ctx.next();
95+
}
96+
97+
// The validate middleware will run before the createCustomer handler
98+
Nitric.api("public").post("/customers", createCustomer, middlewares: [validate]);
99+
```
100+
67101
### Access the request body
68102

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

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ api.put("/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,35 @@ api.put("/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+
import '../middlewares';
79+
80+
Future<HttpContext> validate(HttpContext ctx) async {
81+
if (!ctx.req.headers.containsKey("Content-Type")) {
82+
ctx.res.status = 400;
83+
ctx.res.body = "header Content-Type is required";
84+
85+
// End the middleware chain by not calling `ctx.next()`.
86+
return ctx;
87+
}
88+
89+
return ctx.next();
90+
}
91+
92+
Future<HttpContext> createOrUpdateCustomer(HttpContext ctx) async {
93+
// handle the UPDATE request...
94+
return ctx.next();
95+
}
96+
97+
// The validate middleware will run before the createOrUpdateCustomer handler
98+
Nitric.api("public").put("/customers", createOrUpdateCustomer, middlewares: [validate]);
99+
```
100+
67101
### Access the request body
68102

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

0 commit comments

Comments
 (0)