Capítulo 1.4: Estrutura da API REST
Tempo de estudo: 45 minutos
1. API REST: Arquitetura da estação espacial
Imagine uma estação espacial, onde cada módulo tem:
-
Porta de acoplamento padrão (interface única)
-
Especialização clara (compartimento de habitação, laboratório, armazenamento)
-
Sistema de coordenadas (localização precisa)
A API REST (Representational State Transfer) funciona com os mesmos princípios:
-
Interface única para todos os recursos
-
Separação clara de componentes
-
Endereçamento via URI (coordenadas espaciais)
💡 Ideia chave:
Cada recurso (planetas, foguetes, astronautas) tem um URL único e interage através de métodos HTTP.
2. 6 princípios REST na analogia espacial
Princípio REST | Análogo na ISS | Significado para a API |
---|---|---|
Interface única | Nós de acoplamento padrão | Regras idênticas para todas as requisições |
Stateless | Cada comando é autossuficiente | O servidor não armazena o estado do cliente |
Cache | Reservas locais de provisões | Armazenamento de respostas frequentes |
Cliente-servidor | Separação clara: MCC ↔ Estação | Desenvolvimento independente de componentes |
Multicamadas | Satélites retransmissores | Proxies, balanceadores de carga |
Código sob demanda | Download de software para experimentos | (Opcional) Transmissão de scripts |
3. Recursos e URI: Coordenadas espaciais
Cada objeto na API é um recurso com um endereço único:
https://api.spacexdata.com/v4/ ← URL Base
rockets/ ← Coleção de foguetes
rockets/5e9d0d95eda69973a809d1ec ← Foguete específico (por ID)
Exemplos de recursos espaciais:
GET /stars
→ Lista de estrelasGET /stars/sirius
→ Dados sobre SíriusPOST /satellites
→ Lançar um novo satélitePUT /missions/artemis
→ Atualizar missão
Esquema de hierarquia URI:
[URL Base]
├── /planets → Coleção de planetas
│ ├── /mars → Recurso "Marte"
│ └── /venus → Recurso "Vênus"
└── /launches → Coleção de lançamentos
├── /upcoming → Subcoleção
└── /latest → Recurso
4. Operações CRUD via métodos HTTP
Operação | Método HTTP | Exemplo (Estação espacial) | Resposta do servidor |
---|---|---|---|
Create | POST |
Enviar novo módulo | 201 Created |
Read | GET |
Solicitar dados sobre o módulo | 200 OK |
Update | PUT |
Reconfigurar módulo | 200 OK |
Delete | DELETE |
Desacoplar módulo antigo | 204 No Content |
⚡ Exemplo de código (Adicionar satélite):
import requests
# Usamos um serviço de teste que simula a criação de um recurso
new_post = {
"title": "New Telescope Launch",
"body": "Hubble-2 is ready for deployment.",
"userId": 1
}
# Chave API condicional para demonstração de cabeçalhos
headers = {
"Authorization": "Bearer YOUR_DEMO_KEY",
"Content-Type": "application/json; charset=UTF-8"
}
response = requests.post(
"https://jsonplaceholder.typicode.com/posts",
json=new_post,
headers=headers
)
if response.status_code == 201:
print("✅ Postagem sobre o novo satélite criada com sucesso!")
print("Resposta do servidor:")
print(response.json())
else:
print(f"❌ Erro! Status: {response.status_code}")
5. Versionamento da API: Evolução da estação
Assim como a ISS é atualizada (Módulo "Zarya" → "Nauka"), a API muda de versão:
- No URL:
https://api.spacex.com/v4/rockets
- Nos cabeçalhos:
Accept: application/vnd.spacex-v5+json
Por que é importante:
- v1: Funcionalidade básica
- v2: Novos campos adicionados
- v3: Estrutura das respostas alterada
⚠️ Dica: Sempre especifique a versão nas requisições, caso contrário, a "acoplagem" pode falhar!
6. Hipermídia (HATEOAS): Navegação no espaço
A resposta da API contém links para recursos relacionados — como um mapa da estação:
{
"id": "iss",
"name": "Estação Espacial Internacional",
"crew": 7,
"_links": {
"self": { "href": "/stations/iss" },
"modules": { "href": "/stations/iss/modules" },
"schedule": { "href": "/stations/iss/schedule" }
}
}
Quiz para fixação
🚀 Conclusão do capítulo:
A API REST é uma "arquitetura de estação espacial" padronizada para serviços web. Lembre-se:
- Recursos = Objetos (foguetes, planetas)
- URI = Coordenadas de objetos
- Métodos HTTP = Comandos de controle
- Versões = Modernizações da estação
Final da preparação! No próximo capítulo, lançaremos uma "sonda de teste" — aprenderemos a testar APIs via Postman.
📌 Prática: Estude a estrutura da API SpaceX e tente executar:
GET https://api.spacexdata.com/v4/launches/latest
— observe o URI e a estrutura JSON!