
# spring_web_dart

`spring_web_dart` is the shared web vocabulary of the Spring for Dart packages: the annotations that describe an HTTP call, the types of HTTP itself (headers, status codes, media types, response bodies, errors), and clients that send HTTP and WebSocket requests on the VM, in Flutter and in the browser.

## Why

You describe an HTTP endpoint once, with annotations on a Dart method:

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

Two other packages read the same annotations from opposite sides:

- [spring_boot_starter_web](../spring-boot-starter-web/index.md) is a web server. On a `@RestController` class, the method above answers `GET /books/978-0`.
- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md) is an HTTP client. On a `@FeignClient` interface, the method above sends `GET /books/978-0` and reads the answer into a `Book`.

Keeping the vocabulary in its own package lets the server, the clients, the WebSocket starter and libraries share it without depending on each other, and lets a Flutter app use the clients without a server.

## Setup

Most applications never add this package by hand: it comes with the web, Feign and WebSocket starters, which re-export it. Add it directly when you want only the HTTP and WebSocket clients, or when you write a library that reads the annotations or works with the server types.

```yaml
# pubspec.yaml
dependencies:
  spring_web_dart: ^0.9.0
```

Its only dependency is `spring_core_dart`, and it needs no code generation by itself. Imports:

| Import | Holds |
|---|---|
| `package:spring_web_dart/spring_web_dart.dart` | Everything, with `platformHttpTransport()` and `platformWebSocketTransport()`. |
| `package:spring_web_dart/io.dart` | `IoHttpTransport`, `IoWebSocketTransport` (`dart:io`). |
| `package:spring_web_dart/browser.dart` | `FetchHttpTransport`, `BrowserWebSocketTransport`. |
| `package:spring_web_dart/testing.dart` | `MockHttpTransport`, `MockWebSocketTransport`, `MockServerHttpRequest`, `MockServerHttpResponse`, `MockMultipartFile`, `WebSocketSessionPair`. |

## Example

With this package alone you can send HTTP requests from any platform:

```dart
import 'package:spring_web_dart/spring_web_dart.dart';

Future<void> main() async {
  final transport = platformHttpTransport();
  final response = await transport.send(
    HttpRequest(
      method: HttpMethod.get,
      url: Uri.parse('https://api.neon.books/books/978-0'),
      headers: HttpHeaders({HttpHeaders.acceptHeader: MediaType.applicationJson}),
      timeout: const Duration(seconds: 5), // give up on a slow server
    ),
  );
  // Every status is a response; only network failures throw.
  if (response.statusCode.is2xxSuccessful) print(response.bodyText);
  transport.close();
}
```

`HttpHeaders`, `HttpStatus`, `HttpRequest` and `HttpResponse` have the same names as classes of `dart:io`. In a file that needs both, import `dart:io` with a prefix (`import 'dart:io' as io;`) or `hide` them.

## Configuration

`spring_web_dart` has no properties of its own: it is a library of types, configured in code (`platformHttpTransport(connectTimeout:)`, `IoWebSocketTransport(maxTextMessageSize:)`). The starters that use it read properties for it: `server.*` and `spring.mvc.*` in the web starter, `spring.feign.*` in the Feign starter, `spring.websocket.client.*` in the WebSocket starter.

## What is inside

- [Mapping annotations](mapping-annotations.md): `@GetMapping`, `@PathVariable`, `@RequestParam`, `@RequestBody` and the rest, for servers and clients.
- [Controller annotations](controller-annotations.md): `@RestController`, `@ResponseStatus`, `@ExceptionHandler`, `@ControllerAdvice`, `@CrossOrigin`.
- [HTTP types](http-types.md): `ResponseEntity`, `HttpHeaders`, `HttpStatus`, `MediaType`, `ProblemDetail`, multipart.
- [HTTP transport](http-transport.md): `HttpTransport`, timeouts, streaming responses.
- [Server-sent events](server-sent-events.md): `EventStream<T>`, reconnection, the decoder.
- [WebSocket transport](websocket-transport.md): `WebSocketTransport`, `WebSocketSession`, limits.
- [Server side](server-side.md): `ServerHttpRequest`, `HandlerMapping`, `PathPattern`, `RequestDeadline`, `AllowedOrigins`.
- [Testing](testing.md): `MockHttpTransport`, `MockWebSocketTransport`, server mocks.
- [Differences from Spring](differences.md): what works differently than in Spring Web.

## In Spring (Java)

In Spring these types are spread over `spring-web` (annotations, `ResponseEntity`, `HttpHeaders`, `ProblemDetail`), `spring-webmvc` and `spring-websocket`. Here they are one small package that runs everywhere Dart runs, browser included. The annotations take Dart's shape: `.of` constructors for named attributes, and no `required` or `defaultValue`.

## See also

- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md)
- [spring_boot_starter_websocket](../spring-boot-starter-websocket/index.md)
