
# HTTP clients

This page makes the same call three ways: fetch a book as JSON from a catalog service, decode it into a class, send a token, treat a 404 as "no such book", limit the time and retry when the connection fails.

- **`platformHttpTransport()`** from `spring_web_dart`: a small HTTP layer that works on the VM, in Flutter and in the browser. Used by hand, it is the plain Dart baseline.
- **`dio`**: the popular HTTP client package, with options and interceptors.
- **A Feign client** from `spring_boot_starter_feign`: an annotated interface whose implementation the generator writes.

The plain versions decode with a hand-written `fromJson`:

```dart
class Book {
  const Book({required this.isbn, required this.title});

  factory Book.fromJson(Map<String, dynamic> json) =>
      Book(isbn: json['isbn'] as String, title: json['title'] as String);

  final String isbn;
  final String title;
}
```

## Fetch and decode

**platformHttpTransport.** You build the request, send it, check the status and decode the body.

```dart
final transport = platformHttpTransport();

Future<Book> find(String isbn) async {
  final response = await transport.send(HttpRequest(
    method: HttpMethod.get,
    url: Uri.parse('https://api.neon.books/books/$isbn'),
  ));
  if (!response.isSuccess) throw StateError('catalog: ${response.statusCode}');
  return Book.fromJson(jsonDecode(response.bodyText) as Map<String, dynamic>);
}
```

**dio.** The base URL is set once; `data` is already decoded from JSON. A status outside 2xx throws by default.

```dart
final dio = Dio(BaseOptions(baseUrl: 'https://api.neon.books'));

Future<Book> find(String isbn) async {
  final response = await dio.get<Map<String, dynamic>>('/books/$isbn');
  return Book.fromJson(response.data!);
}
```

**Feign.** One method per endpoint. `Book` needs no `fromJson`: classes a client returns are described for JSON from their constructor when they are in the same package.

```dart
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogClient {
  @GetMapping('/books/{isbn}')
  Future<Book> find(@PathVariable() String isbn);
}

@Service()
class Shelf {
  Shelf(this.catalog); // the generated client, injected
  final CatalogClient catalog;
}
```

```properties
catalog.url=https://api.neon.books
```

What changes: with the transport you write everything; dio removes the URL joining and the decoding step; Feign removes the method body. The Feign client needs `build_runner`, and the call only exists inside a Spring application, where it is injected.

## A header on every request

**platformHttpTransport.** Added to each request you build.

```dart
headers: HttpHeaders()..setBearerAuth(tokens.accessToken),
```

**dio.** An interceptor, added once.

```dart
dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) {
    options.headers['Authorization'] = 'Bearer ${tokens.accessToken}';
    handler.next(options);
  },
));
```

**Feign.** A `RequestInterceptor` bean applies to every client; a ready-made one sends a bearer token.

```dart
@Configuration()
class FeignSetup {
  @Bean()
  RequestInterceptor auth(TokenStore tokens) =>
      BearerTokenRequestInterceptor(() => tokens.accessToken);
}
```

A fixed header can also come from configuration: `spring.feign.client.config.catalog.default-request-headers.X-Api-Key=${CATALOG_KEY}`.

What changes: dio and Feign both set it once. Feign's interceptor runs again for every retry, so a refreshed token reaches the next attempt, and it can be limited to one client.

## A missing book (404)

**platformHttpTransport.** Every status is a normal response, so a 404 is a check.

```dart
if (response.statusCode == HttpStatus.notFound) return null;
```

**dio.** A 404 throws a `DioException` that carries the response.

```dart
try {
  return Book.fromJson((await dio.get<Map<String, dynamic>>('/books/$isbn')).data!);
} on DioException catch (e) {
  if (e.response?.statusCode == 404) return null;
  rethrow;
}
```

**Feign.** A 404 throws `FeignNotFound`. Or let the client answer `null`:

```dart
@GetMapping('/books/{isbn}')
Future<Book?> find(@PathVariable() String isbn);
```

```properties
spring.feign.client.config.catalog.dismiss404=true
```

What changes: Feign has one exception class per status (`FeignNotFound`, `FeignConflict`, `FeignServiceUnavailable`, ...), so a `catch` names the case it handles. `dismiss404` turns the most common case into configuration.

## Timeouts

**platformHttpTransport.** A connect timeout on the transport; on the request, a read timeout (each wait for data) and a deadline for the whole exchange. A timeout throws `HttpTransportException` with `isTimeout` set.

```dart
final transport = platformHttpTransport(connectTimeout: const Duration(seconds: 3));

HttpRequest(
  method: HttpMethod.get,
  url: url,
  readTimeout: const Duration(seconds: 10),
  timeout: const Duration(seconds: 15),
);
```

**dio.** On the options; a timeout is a `DioException` with type `connectionTimeout` or `receiveTimeout`.

```dart
final dio = Dio(BaseOptions(
  baseUrl: 'https://api.neon.books',
  connectTimeout: const Duration(seconds: 3),
  receiveTimeout: const Duration(seconds: 10),
));
```

**Feign.** In configuration, per client or for all of them.

```properties
spring.feign.client.config.default.connect-timeout=3s
spring.feign.client.config.catalog.read-timeout=10s
spring.feign.client.config.catalog.call-timeout=15s
```

What changes: the values move from code to a file, so a test or a profile can change them. `call-timeout` bounds the whole call, every retry and pause included, and throws `FeignCallTimeoutException`. A Feign call made while a web request is handled is also limited by that request's deadline.

## Retries

**platformHttpTransport.** A loop you write.

```dart
for (var attempt = 1; ; attempt++) {
  try {
    return await send();
  } on HttpTransportException {
    if (attempt == 3) rethrow;
    await Future<void>.delayed(Duration(milliseconds: 150 * attempt));
  }
}
```

**dio.** Not built in. The `dio_smart_retry` package adds an interceptor:

```dart
dio.interceptors.add(RetryInterceptor(
  dio: dio,
  retries: 2,
  retryDelays: const [Duration(milliseconds: 150), Duration(milliseconds: 225)],
));
```

**Feign.** A `Retryer` bean, for all clients or, with the `retryer` property, for one.

```dart
@Bean()
Retryer retryer() => const DefaultRetryer(maxAttempts: 3); // pauses of 150 ms, then 225 ms
```

What changes: Feign retries only what may succeed later: connection errors, timeouts and answers with `Retry-After`. An error status alone, such as a plain 503, is not retried unless an `ErrorDecoder` returns a `RetryableException` for it. Nothing is retried until a `Retryer` is declared.

## In short

| Task | `platformHttpTransport()` | `dio` | Feign client |
|---|---|---|---|
| Base URL | by hand | `BaseOptions(baseUrl:)` | `@FeignClient(url:)`, from configuration |
| JSON | `jsonDecode` + `fromJson` | decoded `data` + `fromJson` | automatic for the return type |
| Header on every call | per request | interceptor | `RequestInterceptor` bean, or a property |
| 404 | a status check | `DioException`, check `response?.statusCode` | `FeignNotFound`, or `dismiss404` gives `null` |
| Timeouts | `connectTimeout`, `readTimeout`, `timeout` in code | `connectTimeout`, `receiveTimeout` in code | `connect-`, `read-`, `call-timeout` in configuration |
| Retry | a loop | `dio_smart_retry` | `Retryer` bean |
| Fallback when all fails | a `catch` | a `catch` | `@FeignClient(fallback:)` |
| Platforms | VM, Flutter, web | VM, Flutter, web | VM, Flutter, web (on the transport) |
| Tests | `MockHttpTransport` | an adapter or a mock library | `BeanOverride<HttpTransport>(MockHttpTransport())` |
| Build step | none | none | `build_runner` |

For one or two calls in a small app, the transport or dio is less to learn and needs no build step. A Feign client pays off when an app calls many endpoints, when timeouts, headers and retries should be configured per environment, or when the app already runs on Spring for Dart. The two can meet: the Feign starter sends through the `HttpTransport` bean, so a transport built on dio can carry Feign's calls.

## See also

- [HTTP transport](../components/spring-web-dart/http-transport.md)
- [spring_boot_starter_feign](../components/spring-boot-starter-feign/index.md)
- [Errors, retries and timeouts](../components/spring-boot-starter-feign/errors-and-retries.md)
- [Interceptors](../components/spring-boot-starter-feign/interceptors.md)
- [Configuration](../components/spring-boot-starter-feign/configuration.md)
- [Testing Feign clients](../components/spring-boot-starter-feign/testing.md)
