Responses and resources

Handlers can return Response.json(data, status: 201), Response.text, Response.html, Response.redirect, Response.stream, Response.noContent(), any JsonSerializable or Responsable, maps, lists, models and paginators. Dates serialize like Carbon's toJSON(): UTC with microseconds, 2026-01-02T03:04:05.000000Z.

API resources#

final class PostResource extends JsonResource<Post> {
  PostResource(super.resource);

  /// Documents the item for `dartisan openapi:generate` (`.returns(...)`).
  static const Map<String, Object?> schema = {
    'type': 'object',
    'properties': {
      'id': {'type': 'integer'},
      'title': {'type': 'string'},
      'published': {'type': 'boolean'},
    },
  };

  @override
  Map<String, Object?> toArray(Request? request) => {
    'id': resource.id,
    'title': resource.title,
    'published': resource.published,
  };
}

• A single resource is wrapped in {"data": {...}}.
• JsonResource.collection(items, PostResource.new) wraps lists, and for paginators produces Laravel's {data, links: {first, last, prev, next}, meta}, where meta is the paginator array without data and the URLs.
• when, whenLoaded, mergeWhen, additional({...}) and withMeta(request) (Laravel's with()) are available.

Errors#

Exceptions are rendered by the exception handler with Laravel's bodies. With APP_DEBUG=false nothing internal leaks:

Register custom renderers with withExceptions((e) => e.render<MyError>((error, request) => Response.json({...}, status: 409))).