Futures, HTTP e JSON

No fim desta aula consegues

• Explicar o que é um Future e porque um pedido à rede nunca pode bloquear a app.
• Ler um pedido e uma resposta HTTP: método, URL, headers, corpo e código de estado.
• Ler a documentação Swagger de uma API: operações, parâmetros, respostas, schemas e erros.
• Converter JSON em objetos Dart com fromJson e saber onde o parsing costuma partir.
• Mostrar dados da rede com FutureBuilder: a carregar, erro e dados.
• Distinguir um Future (um valor) de uma Stream (muitos valores ao longo do tempo).

Um valor que ainda não chegou

• Um pedido à rede demora 50 ms no Wi-Fi da escola e 5 s num túnel. A app não pode ficar parada à espera.
• O Dart corre a tua app numa só linha de execução, que também desenha o ecrã. Se ela esperar, o ecrã congela: nem scroll, nem animações, nem toques.
• Por isso http.get não devolve a resposta: devolve um Future<Response>, uma promessa de que a resposta vem mais tarde.
• Um Future está num de três estados: por completar, completo com um valor ou completo com um erro.

print('1. antes do pedido');
final future = http.get(url); // o pedido parte, a app continua
print('2. o pedido já partiu');
final response = await future; // aqui a função para até chegar a resposta
print('3. chegou: ${response.statusCode}');

async e await

Future<List<Island>> fetchIslands(String token) async {
  final response = await http.get(
    Uri.parse('$baseUrl/v1/islands'),
    headers: {'Authorization': 'Bearer $token'},
  );
  final list = jsonDecode(response.body) as List<dynamic>;
  return list
      .map((item) => Island.fromJson(item as Map<String, dynamic>))
      .toList();
}

• async marca a função: ela devolve sempre um Future, mesmo que o return devolva uma lista.
• await só se usa dentro de uma função async. Lê-se de cima para baixo como código normal.
• Um erro dentro da função (sem rede, JSON errado) completa o Future com erro. Apanha-se com try/catch à volta do await.
• Esquecer o await é o erro mais comum: ficas com um Future na mão em vez da resposta.

HTTP em 10 minutos (1 de 2): pedido e resposta

• GET lê e nunca altera. POST cria. PUT substitui. DELETE apaga.
• Idempotente: repetir o pedido dá o mesmo resultado. GET, PUT e DELETE são; POST não é. Um GET que falhou pode repetir-se; um POST repetido pode criar dois relatos, ou cobrar duas vezes.

Para os testes: a idempotência decide o que a app pode repetir sozinha quando a rede falha.

HTTP em 10 minutos (2 de 2): códigos e erros

Na API do curso, quando algo corre mal o corpo explica o erro em português:

{
  "error": {
    "code": "not_found",
    "message": "Não há nenhuma ilha com o id \"atlantida\"."
  }
}

Para os testes: 4xx é culpa do pedido, 5xx é culpa do servidor, 429 é um limite.

REST, GraphQL, gRPC e WebSockets

Para os testes: REST é o normal em mobile; GraphQL evita pedir dados a mais; gRPC é binário e rápido; WebSockets são para tempo real.

A API do curso

Endereço: https://api-pdm.sublimecipher.com. Documentação completa na página API; documentação interativa em /docs.

Ler o Swagger (1 de 4): o mapa da API

• O Swagger é uma página gerada a partir do contrato OpenAPI (/openapi.json): um ficheiro que descreve cada rota, os parâmetros, os dados e os erros. É a fonte de verdade.
• As operações vêm agrupadas por tema. Cada linha é um método e um caminho: GET /v1/islands.
• O cadeado diz que a operação precisa de token. O botão Authorize guarda o token para todos os pedidos da página.

Ler o Swagger (2 de 4): uma operação

• Parameters: o que tens de mandar. id é obrigatório (* required), é texto e vai no caminho (path): /v1/islands/sao-miguel/forecast. Outros vão na query: /v1/trails?islandId=faial.
• Try it out e Execute fazem o pedido a sério. O Swagger mostra o curl, o URL, o código e o corpo da resposta. Se o curl não tiver a linha Authorization: Bearer, faltou o Authorize.
• Responses: uma entrada por código possível (200, 401, 404, 502), cada uma com um exemplo. É a lista de casos que a tua app tem de tratar.

Ler o Swagger (3 de 4): o schema

• Schema (ao lado de Example Value) é a forma exata da resposta. O * vermelho quer dizer que o campo vem sempre.
• Os tipos dizem como ler cada campo em Dart: string, integer, number, objetos dentro de objetos ({ }) e listas ([Day]). Enum é a lista fechada de valores: dá um enum em Dart.

Ler o Swagger (4 de 4): os erros

• Cada código que a operação pode devolver tem uma entrada: em /v1/islands/{id}/forecast são 200, 401, 404 e 502.
• Os erros têm sempre a mesma forma: code para o programa decidir (not_found, unauthorized...), message para mostrar à pessoa.
• A lista de códigos é a lista de casos que o ecrã tem de tratar. Se o Swagger diz que pode vir 502, a app tem de ter o que mostrar quando vier.

Parte 1: toda a gente com token

Ninguém passa à parte 2 sem o nome no ecrã.

Parte 2: caça ao erro

A API tem agora erros de propósito: respostas que não cumprem o contrato do Swagger. Cada missão diz onde procurar; o erro encontras tu.

Para cada erro, anota três coisas: o pedido, o que o contrato diz e o que chegou.

Do JSON ao objeto Dart

A resposta chega como texto. Até ser um objeto que a app pode usar passa sempre pelos mesmos dois passos: descodificar e dar tipos.

Uma ilha: do JSON ao Island

{
  "id": "sao-miguel",
  "name": "São Miguel",
  "imageUrl": "https://api-pdm.sublimecipher.com/static/islands/sao_miguel.jpg",
  "trailCount": 3
}

factory Island.fromJson(Map<String, dynamic> json) {
  return Island(
    id: json['id'] as String,
    name: json['name'] as String,
    imageUrl: json['imageUrl'] as String,
  );
}

JSON com objetos dentro de objetos

{
  "date": "2026-10-14",
  "weatherType": {
    "id": 7,
    "description": "Aguaceiros/chuva fracos",
    "category": "rain"
  },
  "tMin": 20.0,
  "tMax": 24.2,
  "rainChance": 57,
  "wind": {
    "direction": "SW",
    "class": 2,
    "description": "Moderado"
  }
}

• Um objeto dentro de outro é mais um Map; uma lista é uma List<dynamic> que se percorre com map.
• O JSON não tem datas nem enums: vêm como texto, e o fromJson converte (DateTime.parse, values.byName).

Um dia: DayForecast.fromJson

factory DayForecast.fromJson(Map<String, dynamic> json) {
  final weather = json['weatherType'] as Map<String, dynamic>;
  final wind = json['wind'] as Map<String, dynamic>;
  return DayForecast(
    date: DateTime.parse(json['date'] as String),
    type: WeatherType.values.byName(weather['category'] as String),
    tMin: (json['tMin'] as num).toDouble(),
    tMax: (json['tMax'] as num).toDouble(),
    rainChance: json['rainChance'] as int,
    windClass: wind['class'] as int,
  );
}

• O modelo da app não tem de ser igual ao JSON. O IPMA não dá o vento em km/h, só a classe: o windKmh das aulas passa a windClass.

Onde o parsing parte

• Um erro no fromJson completa o Future com erro: o ecrã mostra a mensagem de erro em vez dos dados, mas a app não fecha.
• O contrato da API (a página API e o /openapi.json) diz o que pode faltar. O que não está no contrato, não contes com isso.

O pedido completo, com erros

void _check(http.Response response) {
  if (response.statusCode >= 200 && response.statusCode < 300) return;
  final body = jsonDecode(response.body) as Map<String, dynamic>;
  final error = body['error'] as Map<String, dynamic>;
  throw ApiException(response.statusCode, error['message'] as String);
}

Future<List<Island>> fetchIslands(String token) async {
  final response = await http
      .get(
        Uri.parse('$baseUrl/v1/islands'),
        headers: {'Authorization': 'Bearer $token'},
      )
      .timeout(const Duration(seconds: 10));
  _check(response);
  final list = jsonDecode(response.body) as List<dynamic>;
  return list
      .map((item) => Island.fromJson(item as Map<String, dynamic>))
      .toList();
}

• O http não lança erro num 404 ou num 500: a resposta chega na mesma. Quem verifica o statusCode és tu.
• Sem timeout, um pedido num túnel pode ficar pendurado minutos. Com ele, ao fim de 10 s o Future completa com erro.

O token e o segredo

Future<String> fetchToken(String clientId, String clientSecret) async {
  final response = await http.post(
    Uri.parse('$baseUrl/v1/auth/token'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({'clientId': clientId, 'clientSecret': clientSecret}),
  );
  _check(response);
  final json = jsonDecode(response.body) as Map<String, dynamic>;
  return json['accessToken'] as String;
}

const clientId = String.fromEnvironment('CLIENT_ID');
const clientSecret = String.fromEnvironment('CLIENT_SECRET');

flutter run -d chrome \
  --dart-define=CLIENT_ID=pdm-ab12cd \
  --dart-define=CLIENT_SECRET=o-teu-segredo

• Num POST o corpo vai em JSON: jsonEncode faz o contrário do jsonDecode.
• O segredo não vai para o código nem para o git. O --dart-define passa-o na hora de correr.

FutureBuilder: o ecrã que espera

class _IslandsScreenState extends State<IslandsScreen> {
  late final Future<List<Island>> _islands;

  @override
  void initState() {
    super.initState();
    _islands = fetchIslands(widget.token); // once, not in build
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<List<Island>>(
      future: _islands,
      builder: (context, snapshot) {
        if (snapshot.connectionState != ConnectionState.done) {
          return const Center(child: CircularProgressIndicator());
        }
        if (snapshot.hasError) {
          return Center(child: Text('${snapshot.error}'));
        }
        final islands = snapshot.data!;
        return ListView.builder(
          itemCount: islands.length,
          itemBuilder: (context, i) => ListTile(
            leading: Image.network(islands[i].imageUrl, width: 56),
            title: Text(islands[i].name),
          ),
        );
      },
    );
  }
}

FutureBuilder: o que interessa

• O builder corre de novo cada vez que o Future muda de estado. O snapshot diz em que estado está.
• Três ramos, sempre: a carregar (connectionState), erro (hasError, error) e dados (data). Os três estados do Future, desenhados.
• O Future cria-se uma vez, no initState. Se escreveres future: fetchIslands(token) dentro do build, cada rebuild faz um pedido novo.
• Image.network em vez de Image.asset: a fotografia também vem da rede, e o Flutter guarda-a em cache.
• Para voltar a pedir (botão "Tentar de novo"), atribui um Future novo dentro de setState.

E se os dados não param de chegar?

• Um Future é uma encomenda: chega uma vez. Uma Stream é uma assinatura: chega sempre que há uma edição nova, até cancelares.
• De onde vêm os dados em tempo real: polling (a app pergunta de X em X segundos), Server-Sent Events ou WebSockets (o servidor envia quando há novidades).
• O StreamBuilder tem o mesmo snapshot do FutureBuilder, mas o builder corre de novo a cada valor novo.

Até segunda