Vocabulário de web e APIs básico

Nível: A2

Objetivo

Aprender o vocabulário básico de web e APIs (client, server, request, response, endpoint, status code, JSON, token) e entender como descrever uma chamada simples de API em inglês.

Explicação

Quase todo software moderno se comunica com outro software pela web usando uma API (application programming interface). Em uma API, dois lados conversam:

• Client: o aplicativo que pede algo (por exemplo, o app no celular ou a página no navegador).
• Server: o aplicativo que recebe o pedido e devolve uma resposta.

Uma única conversa entre client e server é uma API call (chamada de API). Essa conversa tem sempre duas partes:

• Request: a mensagem que o client envia ao server. O request inclui um endpoint (a URL da API, como `https://api.example.com/v1/users`) e um HTTP method (geralmente `GET` para ler dados ou `POST` para enviar dados novos).
• Response: a mensagem que o server devolve. A response traz um status code (um número de três dígitos que diz o que aconteceu) e, quando dá certo, um body (corpo) com os dados pedidos.

Os status codes mais comuns em APIs REST são:

• `200 OK`: deu certo, a response traz os dados pedidos.
• `201 Created`: deu certo e um novo recurso foi criado (comum em POST).
• `400 Bad Request`: o client mandou algo errado (parâmetro faltando, formato inválido).
• `401 Unauthorized`: falta autenticação ou o token é inválido.
• `404 Not Found`: o endpoint não existe ou o recurso não foi encontrado.
• `500 Internal Server Error`: o server quebrou; o problema está do lado dele, não do client.

O body da response costuma vir em JSON (JavaScript Object Notation), um formato de texto leve para representar dados. Um JSON simples se parece com isto:

```json {"id": 42, "name": "Nina", "role": "engineer"} ```

Quando a API exige autenticação, o client inclui um token (uma credencial) em um header da request, geralmente no campo `Authorization`. O server lê o header, valida o token e, se estiver válido, devolve os dados.

Em uma frase, uma chamada simples de API se resume a: o client faz um `GET` para um endpoint; o server devolve uma response com um status code e, quando dá certo, um body em JSON.

Exemplos

Erros comuns

• Confundir request e response: o client envia o request; o server envia a response.
• Trocar 404 (recurso não encontrado) com 500 (erro no server): 404 geralmente é problema de URL, 500 é problema interno.
• Esquecer o method HTTP: ler dados é GET; criar dados novos é POST. Sem method, a chamada fica incompleta.
• Misturar JSON com JavaScript: JSON é só um formato de texto; o servidor pode ser escrito em qualquer linguagem.
• Colocar o token no body da request em vez do header Authorization: o header é o lugar padrão para credenciais.
• Dizer 'send a response' para o client: o client recebe a response, o server envia a response.

Prática guiada

Leia esta chamada simples e identifique cada parte:

• O client é o app no celular.
• O endpoint é `https://api.weather.example.com/v1/forecast`.
• O method é `GET`.
• O header inclui o token `Authorization: Bearer abc123`.
• A response volta com status `200 OK` e um body em JSON com a temperatura.

Agora responda:

• Who sends the request? — The client (the mobile app) sends the request.
• What is the endpoint? — The endpoint is `/v1/forecast`.
• What does the server return when the call works? — The server returns a 200 OK response with a JSON body.

Observe a ordem: o client envia o request → o server processa → o server devolve a response.

Resumo

Em uma chamada de API, o client envia um request (com method e endpoint) ao server, que devolve uma response com um status code e, quando dá certo, um body em JSON. Status 200 significa OK, 404 significa não encontrado e 500 significa erro no server. Tokens vão no header Authorization para autenticar o client.

História: Vocabulário de web e APIs básico

Nível: A2

História em inglês

A 404 on Friday afternoon

Last Friday, the dashboard team was about to deploy the new weather widget. Marta, a junior developer, opened the terminal and ran a simple test. The client tried to call the weather API, but the request returned a 404 Not Found. "Why did the request fail?" Marta asked her teammate. Her teammate checked the endpoint and noticed the URL was wrong. The dashboard was calling /weather, but the new API only accepts /v1/weather.

How a simple API call works

The senior engineer joined the call and explained the basics. "A simple API call has two sides: the client and the server," she said. The client sends a request to an endpoint, and the server returns a response. Every response has a status code: 200 means OK, 404 means not found, 500 means a server error. When the call works, the response body is usually in JSON format. If the API needs authentication, the client must send a token in the Authorization header.

Fixing the call

Marta updated the endpoint from /weather to /v1/weather. She also added a valid token to the Authorization header. This time, the request returned a 200 OK response with a JSON body. The body looked like: {"city": "Berlin", "temperature": 18, "unit": "C"}. "Now the API call works," Marta wrote in the team channel. The senior engineer replied, "Great. You can deploy the widget to staging now."

Tradução linha por linha

Notas de vocabulário

• client = aplicativo que faz o pedido; no exemplo, o dashboard e o terminal.
• request = mensagem que o client envia ao server; aqui, o GET para /v1/weather.
• response = mensagem que o server devolve; traz o status code e o body.
• endpoint = URL da API; o problema foi o endpoint errado (/weather em vez de /v1/weather).
• status code = número de três dígitos na response; 200 = OK, 404 = não encontrado, 500 = erro no server.
• JSON = formato de texto do body; exemplo da história: {"city": "Berlin", "temperature": 18}.
• token = credencial enviada no header Authorization para autenticar o client.
• API call = uma conversa completa entre client e server; neste caso, o GET para /v1/weather.

Perguntas de compreensão

1. What status code did the first request return?
2. Why did the request return 404?
3. What are the two sides of a simple API call, according to the senior engineer?
4. Where should the client send the authentication token?
5. What status code did the request return after Marta fixed the endpoint?
6. What was the format of the response body?

Prática com a história

1. Traduza: O client envia um request GET para o endpoint /v1/orders.
2. Pergunte a um colega se a chamada de API retornou 200 OK.
3. Complete: 'Send the API key as a ___ in the Authorization header.'
4. Escreva uma frase em inglês dizendo que o server retornou 404 porque o endpoint está errado.