SuperAPI AI Directory

relic-request-response

General & other

View repository

Updated 10-16 05:54

About this skill

Relic Requests & Responses

Request object

Every handler receives a Request with these key properties:

  • method -- Method enum (Method.get, Method.post, etc.)
  • url -- full original URI
  • headers -- type-safe header access
  • body -- Body wrapper (single-read stream)
  • pathParameters -- route parameters set by routing
  • queryParameters -- 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']),
);