Skip to content

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 estrelas
  • GET /stars/sirius → Dados sobre Sírius
  • POST /satellites → Lançar um novo satélite
  • PUT /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

1. REST significa:

2. O princípio "Stateless" significa:

3. URI para obter dados sobre o foguete Falcon Heavy:

4. Método para atualização completa de um recurso:

5. HATEOAS na API é:


🚀 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!