serverpod Relic Requests & Responses
Request object
Every handler receives a Request with these key properties:
method--Methodenum (Method.get,Method.post, etc.)url-- full original URIheaders-- type-safe header accessbody--Bodywrapper (single-read stream)pathParameters-- route parameters set by routingqueryParameters-- query string parameters
Request.headers is immutable. Request.body is mutable (middleware may replace it), but the underlying stream can only be read once.
Query parameters
Raw access
app.get('/search', (req) {
final query = req.queryParameters.raw['query'];
final page = req.queryParameters.raw['page'];
return Response.ok(body: Body.fromString('Search: $query, page: $page'));
});
Typed query parameters
const pageParam = IntQueryParam('page');
const limitParam = IntQueryParam('limit');
const priceParam = DoubleQueryParam('price');
app.get('/products', (req) {
final page = req.queryParameters.get(pageParam); // int (throws if missing)
final limit = req.queryParameters.get(limitParam); // int
final maxPrice = req.queryParameters.get(priceParam); // double
return Response.ok(body: Body.fromString('page=$page limit=$limit price=$maxPrice'));
});
Nullable variant:
final page = req.queryParameters(pageParam); // int? -- null if missing
Built-in: IntQueryParam, DoubleQueryParam, NumQueryParam. Custom:
const sortParam = QueryParam<SortOrder>('sort', SortOrder.parse);
const fromParam = QueryParam<DateTime>('from', DateTime.parse);
Reusable specialization:
final class DateTimeQueryParam extends QueryParam<DateTime> {
const DateTimeQueryParam(String key) : super(key, DateTime.parse);
}
Multiple values
app.get('/filter', (req) {
final tags = req.url.queryParametersAll['tag'] ?? []; // List<String>
return Response.ok(body: Body.fromString('Tags: $tags'));
});
// GET /filter?tag=dart&tag=server → Tags: [dart, server]
Reading headers
app.get('/info', (req) {
final userAgent = req.headers.userAgent; // String?
final contentLength = req.headers.contentLength; // int?
final mimeType = req.mimeType; // MimeType?
// ...
});
Authorization
app.get('/protected', (req) {
final auth = req.headers.authorization;
if (auth is BearerAuthorizationHeader) {
final token = auth.token;
return Response.ok(body: Body.fromString('Token: $token'));
} else if (auth is BasicAuthorizationHeader) {
final username = auth.username;
return Response.ok(body: Body.fromString('User: $username'));
}
return Response.unauthorized();
});
Reading the request body
The body can only be read once. A second read throws StateError.
As string
app.post('/submit', (req) async {
final text = await req.readAsString();
return Response.ok(body: Body.fromString('Received: $text'));
});
JSON parsing
app.post('/api/users', (req) async {
try {
final body = await req.readAsString();
final data = jsonDecode(body) as Map<String, dynamic>;
final name = data['name'] as String?;
final email = data['email'] as String?;
if (name == null || email == null) {
return Response.badRequest(
body: Body.fromString(
jsonEncode({'error': 'Name and email are required'}),
mimeType: MimeType.json,
),
);
}
return Response.ok(
body: Body.fromString(
jsonEncode({'message': 'User created', 'name': name}),
mimeType: MimeType.json,
),
);
} catch (e) {
return Response.badRequest(
body: Body.fromString(jsonEncode({'error': 'Invalid JSON: $e'}), mimeType: MimeType.json),
);
}
});
Byte stream
app.post('/upload', (req) async {
if (req.isEmpty) {
return Response.badRequest(body: Body.fromString('Body required'));
}
final stream = req.read(); // Stream<Uint8List>
int totalBytes = 0;
await for (final chunk in stream) {
totalBytes += chunk.length;
}
return Response.ok(body: Body.fromString('Received $totalBytes bytes'));
});
Size-limited reads
const maxFileSize = 10 * 1024 * 1024; // 10 MB
final sink = file.openWrite();
try {
await sink.addStream(req.read(maxLength: maxFileSize));
} on MaxBodySizeExceeded {
return Response.badRequest(body: Body.fromString('File too large'));
} finally {
await sink.close();
}
Creating responses
Status code constructors
Response.ok(body: Body.fromString('Success')) // 200
Response.noContent() // 204
Response.badRequest(body: Body.fromString('Bad input')) // 400
Response.unauthorized() // 401
Response.notFound() // 404
Response.internalServerError() // 500
Response(418, body: Body.fromString('I am a teapot')) // custom
Body types
// Text (auto-detects MIME: JSON, HTML, XML, or plain text)
Body.fromString('Hello') // text/plain
Body.fromString('{"key": "value"}') // application/json
Body.fromString('<!DOCTYPE html><html>...</html>') // text/html
// Explicit MIME type
Body.fromString('<html>...</html>', mimeType: MimeType.html)
Body.fromString(jsonEncode(data), mimeType: MimeType.json)
// Binary (auto-detects PNG, JPEG, PDF, etc.)
Body.fromData(imageBytes) // image/png, etc.
Body.fromData(data, mimeType: MimeType.octetStream) // explicit
// Streaming (for large payloads)
Body.fromDataStream(fileStream, contentLength: fileSize) // known size
Body.fromDataStream(dynamicStream) // chunked encoding
// Empty
Body.empty()
Encoding defaults to UTF-8. Override with:
Body.fromString('Café', mimeType: MimeType.plainText, encoding: latin1)
Response headers
app.get('/api/data', (req) {
final headers = Headers.build((h) {
h.cacheControl = CacheControlHeader(maxAge: 3600, publicCache: true);
h['X-Custom-Header'] = ['value'];
});
return Response.ok(
headers: headers,
body: Body.fromString(jsonEncode({'status': 'ok'}), mimeType: MimeType.json),
);
});
HTML response
app.get('/page', (req) {
final html = '<!DOCTYPE html><html><body><h1>Welcome</h1></body></html>';
return Response.ok(body: Body.fromString(html, mimeType: MimeType.html));
});
Streaming response
app.get('/stream', (req) async {
Stream<Uint8List> generate() async* {
for (var i = 0; i < 100; i++) {
await Future<void>.delayed(Duration(milliseconds: 50));
yield utf8.encode('{"item": $i}\n');
}
}
return Response.ok(
body: Body.fromDataStream(generate(), mimeType: MimeType.json),
);
});
Modifying requests
Request is immutable. Use copyWith to create a modified copy:
final rewritten = request.copyWith(
url: request.url.replace(path: '/new-path'),
);
final modified = request.copyWith(
url: request.url.replace(path: '/other'),
headers: Headers.build((h) => h['X-Custom'] = ['value']),
);