Endpoints

Endpoints in Spark are used to create API routes that return data (JSON, String, etc.) rather than full HTML pages. They are perfect for building REST APIs.

Basic Usage

To create an endpoint, annotate a class with `@Endpoint` and extend `SparkEndpoint`. You must implement the `handler` method.

@Endpoint(path: '/api/health', method: 'GET')
class HealthEndpoint extends SparkEndpoint {
  @override
  Future<String> handler(SparkRequest request) async {
    return 'OK';
  }
}

Request Body

To handle request bodies (e.g., JSON), extend `SparkEndpointWithBody<T>`. Spark will automatically parse the JSON body into your DTO class.

Your DTO must have a `fromJson` constructor.

class CreateUserDto {
  final String name;
  CreateUserDto.fromJson(Map<String, dynamic> json) : name = json['name'];
}

@Endpoint(path: '/api/users', method: 'POST')
class CreateUserEndpoint extends SparkEndpointWithBody<CreateUserDto> {
  @override
  Future<Response> handler(SparkRequest request, CreateUserDto body) async {
    // body is already parsed!
    return Response.ok('User ${body.name} created');
  }
}

Responses

The `handler` can return:

• A primitive (String, Map, List) which will be automatically serialized.
• A custom object (must have `toJson()` method).
• A `Response` object for full control over status codes and headers.
• A `Future` of any of the above.

Returning Custom Objects

Spark will automatically call `.toJson()` on your object and serialize the result.

class UserResponse {
  final String name;
  UserResponse(this.name);
  Map<String, dynamic> toJson() => {'name': name};
}

@Endpoint(path: '/api/me', method: 'GET')
class MeEndpoint extends SparkEndpoint {
  @override
  Future<UserResponse> handler(SparkRequest request) async {
    return UserResponse('John Endpoint');
  }
}

Middleware

You can add middleware to specific endpoints by overriding the `middleware` getter.

@Endpoint(path: '/api/protected', method: 'GET')
class ProtectedEndpoint extends SparkEndpoint {
  @override
  List<Middleware> get middleware => [AuthMiddleware()];

  @override
  Future<String> handler(SparkRequest request) async {
    return 'Secret Data';
  }
}