# APIs - Guía Completa y Técnica

## Introducción Conceptual

### ¿Qué es una API?

**Definición técnica**: Application Programming Interface - protocolo de comunicación entre sistemas de software.

**Metáfora del Restaurante** (Modelo Mental):
```
Cliente (Tú) → Camarero (API) → Cocina (Servidor) → Platos (Datos) → Cliente

1. Cliente: Usuario/Agente IA que necesita datos
2. Camarero: API que transporta solicitudes y respuestas  
3. Cocina: Servidor que procesa los datos
4. Platos: Datos estructurados que se devuelven
```

### Importancia Crítica de las APIs

#### Por qué son Fundamentales:
```
✓ Sin API = Software sordo, ciego y mudo
✓ Permiten interoperabilidad entre sistemas
✓ Automatizan procesos sin intervención humana
✓ Crean sistemas de causa-efecto autónomos
✓ Base de todas las automatizaciones modernas
```

#### Impacto en Automatización:
```
Con API: Formulario → Envío → API → CRM → Email automático
Sin API: Formulario → Envío → Intervención manual → CRM → Email manual
```

### Aplicaciones Cotidianas de APIs
```
- Clima en móvil: App → API weather service → Datos temperatura
- PayPal payments: Web → PayPal API → Procesamiento pago
- Google Maps: App → Maps API → Ubicación/direcciones
- Social login: "Login with Google" → Google API → Autenticación
- Spotify en app: App → Spotify API → Música streaming
```

## Arquitectura y Componentes

### 1. Documentación API (El Menú)

#### ¿Qué contiene?
```
- Endpoints disponibles
- Métodos HTTP permitidos  
- Parámetros requeridos/opcionales
- Formatos de request/response
- Ejemplos de uso
- Códigos de error
- Rate limits
- Autenticación requerida
```

#### Dónde encontrarla:
```
Ubicación típica: 
- dominio.com/api/docs
- dominio.com/developers
- docs.dominio.com
- developer.dominio.com

Ejemplos:
- OpenAI: https://platform.openai.com/docs
- Google: https://developers.google.com
- Stripe: https://stripe.com/docs/api
```

### 2. Endpoints (Los Platos del Menú)

#### Estructura de URL:
```
Base URL + Endpoint = Full API URL

Ejemplo:
Base URL: https://api.weather.com/v1/
Endpoint: /current
Full URL: https://api.weather.com/v1/current

Analogía web:
zara.com/es/hombre/pantalones
├── Base: zara.com  
├── Región: /es
├── Categoría: /hombre  
└── Producto: /pantalones
```

#### Tipos de Endpoints:
```json
GET /users          // Obtener todos los usuarios
GET /users/123      // Obtener usuario específico (ID: 123)
POST /users         // Crear nuevo usuario
PUT /users/123      // Actualizar usuario 123
DELETE /users/123   // Eliminar usuario 123
```

### 3. Métodos HTTP (Verbos de Acción)

```http
GET:    Obtener datos (solo lectura)
POST:   Crear nuevos datos  
PUT:    Actualizar datos existentes
PATCH:  Modificar parcialmente datos
DELETE: Eliminar datos
HEAD:   Obtener solo headers (no body)
```

#### Ejemplo Práctico con Gmail:
```http
GET /gmail/v1/users/me/messages     # Leer emails
POST /gmail/v1/users/me/messages    # Enviar email  
DELETE /gmail/v1/users/me/messages/id # Eliminar email
```

## Autenticación y Seguridad

### Tipos de Autenticación

#### 1. API Key (Más Común)
```http
Header: Authorization: Bearer sk-1234567890abcdef...
Header: X-API-Key: your_api_key_here
Header: api-key: your_api_key_here

Ejemplo OpenAI:
Authorization: Bearer sk-proj-1234567890abcdef...
```

#### 2. OAuth 2.0 (Más Seguro)
```
Flujo:
1. Redirect a provider (Google, Facebook, etc.)
2. Usuario autoriza aplicación
3. Provider devuelve código temporal
4. Intercambio código por access token
5. Usar token en requests subsecuentes

Token format:
Authorization: Bearer ya29.a0AfH6SMC7...
```

#### 3. Basic Auth (Menos Común)
```http
Format: username:password → Base64 encode
Header: Authorization: Basic dXNlcjpwYXNzd29yZA==
```

#### 4. JWT Tokens
```http
Header: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Ventaja: Contiene información del usuario
Uso: APIs más sofisticadas
```

### Gestión Segura de Credentials

#### Mejores Prácticas:
```
✓ NUNCA compartir API keys públicamente
✓ Usar variables de entorno
✓ Rotación regular de keys
✓ Monitorear uso de API keys
✓ Revocar keys comprometidas inmediatamente
✓ Usar diferentes keys por proyecto/ambiente
```

#### Storage en Automatización:
```
Make: Connections → Credenciales encriptadas
n8n: Credentials → Storage seguro
Variables: Environment variables en servidor
```

## Estructura de Requests

### HTTP Request Anatomy

```http
POST https://api.openai.com/v1/chat/completions
Content-Type: application/json
Authorization: Bearer sk-proj-1234567890abcdef...

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "max_tokens": 150,
  "temperature": 0.7
}
```

#### Componentes:
```
1. Method: POST
2. URL: https://api.openai.com/v1/chat/completions
3. Headers: Content-Type, Authorization
4. Body: JSON con parámetros
```

### Body Structure (El Pedido Específico)

#### JSON Format (Más Común):
```json
{
  "key1": "value1",
  "key2": 123,
  "key3": true,
  "key4": ["array", "of", "values"],
  "key5": {
    "nested": "object"
  }
}
```

#### Form Data:
```
key1=value1&key2=value2&key3=value3
Content-Type: application/x-www-form-urlencoded
```

#### Multipart (Para archivos):
```
Content-Type: multipart/form-data
Uso: Upload de imágenes, documentos, etc.
```

### Headers Importantes

```http
Content-Type: application/json          # Formato del body
Accept: application/json                # Formato respuesta esperada
Authorization: Bearer token             # Autenticación
User-Agent: MyApp/1.0                  # Identificación de app
X-RateLimit-Remaining: 999             # Rate limiting info
```

## Estructura de Responses

### HTTP Status Codes

#### Success (2xx):
```
200 OK: Successful GET, PUT, PATCH
201 Created: Successful POST
202 Accepted: Async processing started
204 No Content: Successful DELETE
```

#### Client Error (4xx):
```
400 Bad Request: Invalid request format
401 Unauthorized: Missing/invalid auth
403 Forbidden: Valid auth, insufficient permissions  
404 Not Found: Resource doesn't exist
429 Too Many Requests: Rate limit exceeded
```

#### Server Error (5xx):
```
500 Internal Server Error: Server malfunction
502 Bad Gateway: Upstream server error
503 Service Unavailable: Server overloaded
504 Gateway Timeout: Upstream timeout
```

### Response Body Structure

#### Successful Response:
```json
{
  "status": "success",
  "data": {
    "id": 12345,
    "name": "Angel Martinez",
    "email": "angel@example.com",
    "created_at": "2024-02-18T10:30:00Z"
  },
  "message": "User created successfully"
}
```

#### Error Response:
```json
{
  "status": "error",
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email format is invalid",
    "details": "Expected format: user@domain.com"
  },
  "request_id": "req_1234567890"
}
```

## Implementación Práctica

### En n8n (HTTP Request Node)

```json
{
  "method": "POST",
  "url": "https://api.key.com/v1/generate",
  "authentication": "genericCredentialType",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "prompt": "A beautiful landscape",
    "model": "midjourney",
    "aspect_ratio": "16:9"
  }
}
```

### En Make (HTTP Module)

```json
URL: https://api.key.com/v1/generate
Method: POST
Headers: 
  - Authorization: Bearer [API_KEY]
  - Content-Type: application/json
Body (JSON):
{
  "prompt": "{{prompt_text}}",
  "model": "{{selected_model}}",
  "aspect_ratio": "{{aspect_ratio}}"
}
```

### Manejo de Variables

#### En n8n:
```javascript
{
  "prompt": "{{$json.user_prompt}}",
  "model": "{{$json.selected_model}}",
  "user_id": "{{$node.previous_node.json.user_id}}"
}
```

#### En Make:
```json
Variables vienen del panel derecho:
- Drag & drop desde módulos anteriores
- Mapeo visual automático
- No requiere sintaxis específica
```

## APIs Específicas Importantes

### OpenAI API

#### Chat Completions:
```json
POST https://api.openai.com/v1/chat/completions
{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Hello!"}
  ],
  "max_tokens": 150,
  "temperature": 0.7,
  "stream": false
}
```

#### Image Generation:
```json
POST https://api.openai.com/v1/images/generations
{
  "prompt": "A beautiful sunset over mountains",
  "n": 1,
  "size": "1024x1024",
  "quality": "standard"
}
```

### Google APIs

#### Gmail Send:
```json
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
{
  "raw": "base64_encoded_email"
}
```

#### Sheets Read:
```json
GET https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}
```

### Webhook APIs (Recibir datos)

#### n8n Webhook:
```json
URL: https://your-n8n.com/webhook/unique-id
Methods: GET, POST, PUT, DELETE
Headers: Custom headers acceptance
Body: JSON, Form data, Raw text
```

#### Make Webhook:
```json
URL: https://hook.us1.make.com/unique-webhook-id
Auto-parse: JSON automatic detection
Custom headers: Supported
File uploads: Multipart support
```

## Rate Limiting y Optimización

### Rate Limits Comunes
```
OpenAI: 3,500 requests/minute (depende del tier)
Google: 100 requests/100 seconds/user
Twitter: 300 requests/15 minutes
GitHub: 5,000 requests/hour
```

### Estrategias de Manejo

#### 1. Exponential Backoff:
```
Intento 1: Inmediato
Intento 2: Esperar 1 segundo  
Intento 3: Esperar 2 segundos
Intento 4: Esperar 4 segundos
etc.
```

#### 2. Batch Processing:
```
En lugar de: 1000 requests individuales
Usar: 10 requests de 100 items cada uno
```

#### 3. Caching:
```
Cache responses por tiempo determinado
Evita requests repetitivos innecesarios
```

## Error Handling y Debugging

### Debugging Tools

#### Request Testing:
```
- Postman: GUI para testing de APIs
- curl: Command line testing
- HTTPie: User-friendly command line
- Insomnia: Alternative to Postman
```

#### Common Debug Steps:
```
1. Verify endpoint URL correctness
2. Check authentication headers
3. Validate request body format  
4. Confirm content-type headers
5. Review API key permissions
6. Check rate limiting status
7. Validate response parsing
```

### Error Handling Patterns

#### En n8n:
```json
{
  "continueOnFail": true,
  "retryOnFail": true,
  "maxRetries": 3,
  "waitBetweenRetries": 1000
}
```

#### En Make:
```
- Error routes configuration
- Retry logic setup  
- Fallback scenarios
- Error notifications
```

## Monitoreo y Logs

### Metrics to Track
```
- Request success rate
- Average response time  
- Error rates by type
- Rate limit hit frequency
- Cost per request (if applicable)
- Daily/monthly usage patterns
```

### Logging Best Practices
```
✓ Log all API errors with context
✓ Track request/response for debugging
✓ Monitor authentication failures
✓ Alert on rate limit approaches
✓ Log successful operations for audit
```

## URLs y Recursos

### Documentation Sites
```
- OpenAI: https://platform.openai.com/docs
- Google APIs: https://developers.google.com
- Stripe: https://stripe.com/docs/api  
- Twilio: https://www.twilio.com/docs/api
- GitHub: https://docs.github.com/en/rest
```

### Testing Tools
```
- Postman: https://postman.com
- Insomnia: https://insomnia.rest
- HTTPie: https://httpie.io
- Curl: Built-in command line tool
```

### Learning Resources
```
- REST API Tutorial: https://restfulapi.net
- HTTP Status Codes: https://httpstatuses.com
- JSON Validator: https://jsonlint.com
- Base64 Encoder: https://base64encode.org
```

---

*Este documento proporciona todo el conocimiento técnico necesario para entender, implementar y debuggear cualquier integración de API en sistemas de automatización.*