---
description: "Retrofit (Dio) API client conventions for {{PROJECT_NAME}} — Pillar 4"
alwaysApply: true
---

# Retrofit Standards — {{PROJECT_NAME}}

## API client definition
```dart
@RestApi()
abstract class ProductApiClient {
  factory ProductApiClient(Dio dio, {String? baseUrl}) = _ProductApiClient;

  @GET('/products')
  Future<List<ProductDto>> getProducts(@Query('category') String? category);

  @GET('/products/{id}')
  Future<ProductDto> getProduct(@Path('id') String id);

  @POST('/products')
  Future<ProductDto> createProduct(@Body() CreateProductDto dto);
}
```

## Rules
- **NEVER** edit `*.g.dart` files
- Run `dart run build_runner build` after modifying API client
- All DTOs used in Retrofit must have `fromJson`/`toJson` (via `json_serializable` or Freezed)
- Handle `DioException` in the repository layer — never let it reach the presentation layer
- Use `@Headers({'Content-Type': 'application/json'})` at class level, not per-method