Ejemplos

Esta página contiene ejemplos prácticos de uso de la API.

Configuración Inicial

JavaScript/Node.js

// Importar la librería
import API from '@ejemplo/api-client'

// Crear una instancia
const api = new API({
  baseURL: 'https://api.ejemplo.com/v1',
  token: process.env.API_TOKEN,
  timeout: 30000
})

TypeScript

import API, { APIConfig, User } from '@ejemplo/api-client'

const config: APIConfig = {
  baseURL: 'https://api.ejemplo.com/v1',
  token: process.env.API_TOKEN,
  timeout: 30000
}

const api = new API(config)

Python

from ejemplo_api import APIClient

api = APIClient(
    base_url='https://api.ejemplo.com/v1',
    token=os.environ.get('API_TOKEN'),
    timeout=30
)

Autenticación

Login

// Iniciar sesión
const response = await api.post('/auth/login', {
  email: 'usuario@ejemplo.com',
  password: 'contraseña-segura'
})

// Guardar el token
const { token } = response.data
api.setToken(token)

// También puedes guardar en localStorage (navegador)
localStorage.setItem('token', token)

Logout

// Cerrar sesión
await api.post('/auth/logout')

// Limpiar el token
api.clearToken()
localStorage.removeItem('token')

Refresh Token

// Refrescar el token cuando expira
async function refreshToken() {
  const refreshToken = localStorage.getItem('refreshToken')
  
  const response = await api.post('/auth/refresh', {
    refreshToken
  })
  
  const { token, refreshToken: newRefreshToken } = response.data
  
  api.setToken(token)
  localStorage.setItem('token', token)
  localStorage.setItem('refreshToken', newRefreshToken)
}

CRUD Completo

Crear (Create)

// Crear un nuevo usuario
async function createUser(userData) {
  try {
    const response = await api.post('/users', {
      name: userData.name,
      email: userData.email,
      password: userData.password,
      role: 'user'
    })
    
    console.log('Usuario creado:', response.data)
    return response.data
  } catch (error) {
    console.error('Error al crear usuario:', error.message)
    throw error
  }
}

// Uso
const newUser = await createUser({
  name: 'María García',
  email: 'maria@ejemplo.com',
  password: 'contraseña123'
})

Leer (Read)

// Obtener todos los usuarios con paginación
async function getUsers(page = 1, limit = 10) {
  const response = await api.get('/users', {
    params: { page, limit }
  })
  
  return response.data
}

// Obtener un usuario específico
async function getUser(userId) {
  const response = await api.get(`/users/${userId}`)
  return response.data
}

// Uso
const users = await getUsers(1, 20)
const user = await getUser('123')

Actualizar (Update)

// Actualizar un usuario
async function updateUser(userId, updates) {
  try {
    const response = await api.put(`/users/${userId}`, updates)
    console.log('Usuario actualizado:', response.data)
    return response.data
  } catch (error) {
    if (error.status === 404) {
      console.error('Usuario no encontrado')
    } else {
      console.error('Error al actualizar:', error.message)
    }
    throw error
  }
}

// Uso
const updated = await updateUser('123', {
  name: 'Nuevo Nombre',
  email: 'nuevo@ejemplo.com'
})

Eliminar (Delete)

// Eliminar un usuario
async function deleteUser(userId) {
  try {
    await api.delete(`/users/${userId}`)
    console.log('Usuario eliminado exitosamente')
  } catch (error) {
    console.error('Error al eliminar usuario:', error.message)
    throw error
  }
}

// Uso
await deleteUser('123')

Búsqueda y Filtros

Búsqueda Básica

// Buscar usuarios por nombre o email
async function searchUsers(query) {
  const response = await api.get('/users', {
    params: {
      search: query,
      page: 1,
      limit: 20
    }
  })
  
  return response.data
}

// Uso
const results = await searchUsers('maria')

Filtros Avanzados

// Filtrar usuarios con múltiples criterios
async function filterUsers(filters) {
  const response = await api.get('/users', {
    params: {
      role: filters.role,
      status: filters.status,
      createdAfter: filters.createdAfter,
      createdBefore: filters.createdBefore,
      sortBy: filters.sortBy || 'createdAt',
      sortOrder: filters.sortOrder || 'desc'
    }
  })
  
  return response.data
}

// Uso
const activeAdmins = await filterUsers({
  role: 'admin',
  status: 'active',
  createdAfter: '2025-01-01',
  sortBy: 'name',
  sortOrder: 'asc'
})

Subida de Archivos

Subir Imagen de Perfil

// Subir archivo
async function uploadProfileImage(userId, file) {
  const formData = new FormData()
  formData.append('file', file)
  formData.append('userId', userId)
  
  const response = await api.post('/users/avatar', formData, {
    headers: {
      'Content-Type': 'multipart/form-data'
    }
  })
  
  return response.data
}

// Uso en el navegador
const fileInput = document.getElementById('avatar-input')
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0]
  if (file) {
    const result = await uploadProfileImage('123', file)
    console.log('Imagen subida:', result.url)
  }
})

Subir Múltiples Archivos

async function uploadMultipleFiles(files) {
  const formData = new FormData()
  
  files.forEach((file, index) => {
    formData.append(`file${index}`, file)
  })
  
  const response = await api.post('/files/upload', formData, {
    headers: {
      'Content-Type': 'multipart/form-data'
    }
  })
  
  return response.data
}

Manejo de Errores

Manejo Global de Errores

// Configurar interceptor de errores
api.interceptors.response.use(
  (response) => response,
  (error) => {
    // Manejar diferentes tipos de errores
    switch (error.status) {
      case 401:
        // No autenticado - redirigir al login
        window.location.href = '/login'
        break
        
      case 403:
        // Sin permisos
        alert('No tienes permisos para realizar esta acción')
        break
        
      case 404:
        // No encontrado
        console.error('Recurso no encontrado')
        break
        
      case 422:
        // Error de validación
        if (error.data?.details) {
          error.data.details.forEach(detail => {
            console.error(`${detail.field}: ${detail.message}`)
          })
        }
        break
        
      case 429:
        // Rate limit excedido
        alert('Demasiadas peticiones. Por favor, espera un momento.')
        break
        
      case 500:
        // Error del servidor
        alert('Error del servidor. Por favor, intenta más tarde.')
        break
        
      default:
        console.error('Error:', error.message)
    }
    
    return Promise.reject(error)
  }
)

Reintentos Automáticos

// Función con reintentos exponenciales
async function fetchWithRetry(
  endpoint,
  options = {},
  maxRetries = 3,
  baseDelay = 1000
) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await api.get(endpoint, options)
    } catch (error) {
      const isLastAttempt = attempt === maxRetries - 1
      const shouldRetry = error.status >= 500 || error.status === 429
      
      if (isLastAttempt || !shouldRetry) {
        throw error
      }
      
      // Esperar con backoff exponencial
      const delay = baseDelay * Math.pow(2, attempt)
      console.log(`Reintentando en ${delay}ms...`)
      await new Promise(resolve => setTimeout(resolve, delay))
    }
  }
}

// Uso
const data = await fetchWithRetry('/users', {}, 3, 1000)

Paginación

Paginación Simple

// Obtener todas las páginas
async function getAllUsers() {
  const allUsers = []
  let page = 1
  let hasMore = true
  
  while (hasMore) {
    const response = await api.get('/users', {
      params: { page, limit: 100 }
    })
    
    allUsers.push(...response.data.data)
    
    // Verificar si hay más páginas
    hasMore = page < response.data.pagination.pages
    page++
  }
  
  return allUsers
}

Paginación Infinita (React)

import { useState, useEffect } from 'react'

function UserList() {
  const [users, setUsers] = useState([])
  const [page, setPage] = useState(1)
  const [loading, setLoading] = useState(false)
  const [hasMore, setHasMore] = useState(true)
  
  const loadMore = async () => {
    if (loading || !hasMore) return
    
    setLoading(true)
    try {
      const response = await api.get('/users', {
        params: { page, limit: 20 }
      })
      
      setUsers(prev => [...prev, ...response.data.data])
      setHasMore(page < response.data.pagination.pages)
      setPage(prev => prev + 1)
    } catch (error) {
      console.error('Error cargando usuarios:', error)
    } finally {
      setLoading(false)
    }
  }
  
  useEffect(() => {
    loadMore()
  }, [])
  
  return (
    <div>
      {users.map(user => (
        <div key={user.id}>{user.name}</div>
      ))}
      
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          {loading ? 'Cargando...' : 'Cargar más'}
        </button>
      )}
    </div>
  )
}

Cache y Optimización

Cache Simple

class CachedAPI extends API {
  constructor(config) {
    super(config)
    this.cache = new Map()
    this.cacheDuration = 5 * 60 * 1000 // 5 minutos
  }
  
  async getCached(endpoint, options = {}) {
    const cacheKey = `${endpoint}${JSON.stringify(options)}`
    const cached = this.cache.get(cacheKey)
    
    if (cached && Date.now() - cached.timestamp < this.cacheDuration) {
      return cached.data
    }
    
    const response = await this.get(endpoint, options)
    
    this.cache.set(cacheKey, {
      data: response,
      timestamp: Date.now()
    })
    
    return response
  }
  
  clearCache() {
    this.cache.clear()
  }
}

// Uso
const api = new CachedAPI({ baseURL: 'https://api.ejemplo.com/v1' })
const users = await api.getCached('/users')

WebSocket (Tiempo Real)

// Conectar a WebSocket
class RealtimeAPI {
  constructor(url, token) {
    this.ws = new WebSocket(`${url}?token=${token}`)
    this.listeners = new Map()
    
    this.ws.onmessage = (event) => {
      const message = JSON.parse(event.data)
      const listeners = this.listeners.get(message.type) || []
      listeners.forEach(callback => callback(message.data))
    }
  }
  
  on(event, callback) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, [])
    }
    this.listeners.get(event).push(callback)
  }
  
  send(type, data) {
    this.ws.send(JSON.stringify({ type, data }))
  }
  
  close() {
    this.ws.close()
  }
}

// Uso
const realtime = new RealtimeAPI('wss://api.ejemplo.com/ws', token)

realtime.on('user.created', (user) => {
  console.log('Nuevo usuario:', user)
})

realtime.on('user.updated', (user) => {
  console.log('Usuario actualizado:', user)
})

Próximos Pasos

• Volver a la referencia API
• Ver todos los métodos
• Leer la guía de introducción