0Pricing
AI Agents · Lección

Fundamentos de REST API para desarrolladores de agentes

Métodos HTTP, códigos de estado, cabeceras y formato JSON de solicitudes y respuestas.

Fundamentos de REST API para desarrolladores de agentes es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.

¿Qué es una solicitud HTTP?

Todo agente que se conecta a un servicio externo utiliza HTTP, el lenguaje de la web. Una solicitud HTTP tiene tres partes clave: un método, una URL y encabezados y un cuerpo opcionales.

Considere el método como un verbo que indica al servidor qué desea hacer, y la URL como la dirección del recurso.

import requests

# A simple GET request to a public API
response = requests.get('https://api.example.com/users')
print(response.status_code)  # 200
print(response.text)          # raw JSON string

GET — Obtener datos

GET recupera datos de un servidor. Nunca debe modificar nada. Los agentes utilizan GET para leer perfiles de usuario, obtener listas de tareas o recuperar datos de configuración.

Puede pasar parámetros en la URL como una cadena de consulta mediante el argumento params.

import requests

# Fetch users filtered by role
params = {'role': 'admin', 'page': 1, 'limit': 10}
response = requests.get(
    'https://api.example.com/users',
    params=params
)
# URL becomes: /users?role=admin&page=1&limit=10
data = response.json()
print(data['users'])

POST — Crear recursos

POST envía datos al servidor para crear un recurso nuevo. Los agentes utilizan POST para enviar tareas, mandar mensajes o activar acciones. Los datos se incluyen en el cuerpo de la solicitud como JSON.

Establezca siempre el encabezado Content-Type: application/json; la mayoría de las API lo requieren.

import requests
import json

payload = {
    'title': 'Research competitors',
    'assignee': 'agent-001',
    'priority': 'high'
}

response = requests.post(
    'https://api.example.com/tasks',
    json=payload  # sets Content-Type automatically
)
print(response.status_code)  # 201 Created
new_task = response.json()
print('Created task ID:', new_task['id'])

PUT y PATCH — Actualizar datos

PUT reemplaza un recurso completo con datos nuevos. PATCH actualiza únicamente campos específicos. Los agentes utilizan PUT cuando disponen del objeto completo actualizado, y PATCH para cambios parciales, como actualizar el estado de una tarea.

import requests

task_id = '42'

# PATCH: only update the status field
response = requests.patch(
    f'https://api.example.com/tasks/{task_id}',
    json={'status': 'completed'}
)
print(response.status_code)  # 200

# PUT: replace the whole task object
full_task = {
    'title': 'Research competitors',
    'assignee': 'agent-001',
    'priority': 'low',
    'status': 'completed'
}
response = requests.put(
    f'https://api.example.com/tasks/{task_id}',
    json=full_task
)
print(response.status_code)  # 200

DELETE — Eliminar recursos

DELETE elimina un recurso del servidor. Los agentes utilizan DELETE para limpiar datos temporales, eliminar tareas procesadas o cancelar trabajos programados. La mayoría de las solicitudes DELETE no tienen cuerpo.

Una eliminación correcta suele devolver 204 No Content, es decir, sin cuerpo en la respuesta.

import requests

task_id = '42'

response = requests.delete(
    f'https://api.example.com/tasks/{task_id}'
)

if response.status_code == 204:
    print('Task deleted successfully')
elif response.status_code == 404:
    print('Task not found — already deleted?')
else:
    print('Unexpected status:', response.status_code)

Códigos de estado: éxito 2xx

Los códigos de estado indican a su agente si una solicitud se realizó correctamente o falló. El rango 2xx significa que se realizó correctamente:

  • 200 OK — GET/PUT/PATCH devolvió datos
  • 201 Created — POST creó un recurso nuevo
  • 204 No Content — DELETE se realizó correctamente; no se devolvió ningún cuerpo

Compruebe siempre el código de estado antes de procesar el cuerpo de la respuesta.

import requests

response = requests.post(
    'https://api.example.com/tasks',
    json={'title': 'New task'}
)

if response.status_code == 201:
    task = response.json()
    print('Created:', task['id'])
elif response.status_code == 200:
    print('Updated existing resource')
else:
    print('Unexpected code:', response.status_code)

Códigos de estado: errores del cliente 4xx

Los errores 4xx indican que su agente envió una solicitud incorrecta. Algunos habituales son:

  • 400 Bad Request — JSON no válido o falta un campo obligatorio
  • 401 Unauthorized — falta la clave de API o no es válida
  • 404 Not Found — el recurso no existe
  • 429 Too Many Requests — se superó el límite de solicitudes

Estos errores requieren que su agente corrija la solicitud, no que vuelva a intentarlo a ciegas.

import requests

response = requests.get(
    'https://api.example.com/tasks/9999',
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

if response.status_code == 401:
    print('AUTH ERROR: Check your API key')
elif response.status_code == 404:
    print('Task not found')
elif response.status_code == 429:
    retry_after = response.headers.get('Retry-After', 60)
    print(f'Rate limited. Wait {retry_after}s')
elif response.status_code == 400:
    print('Bad request:', response.json().get('error'))

Códigos de estado: errores del servidor 5xx

Los errores 5xx indican que algo salió mal en el servidor; su agente no hizo nada incorrecto. Algunos habituales son:

  • 500 Internal Server Error — error o caída del servidor
  • 502 Bad Gateway — fallo del servicio ascendente
  • 503 Service Unavailable — el servidor está sobrecargado o inactivo

Es seguro volver a intentarlo después de esperar brevemente.

import requests
import time

def get_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code < 500:
            return response  # success or client error
        wait = 2 ** attempt
        print(f'Server error {response.status_code}, retrying in {wait}s...')
        time.sleep(wait)
    return response  # return last response after retries

Encabezados de la solicitud

Los encabezados transportan metadatos con cada solicitud. Los más importantes para los agentes son:

  • Content-Type: application/json — indica al servidor que el cuerpo contiene JSON
  • Authorization: Bearer TOKEN — autentica su solicitud
  • Accept: application/json — indica al servidor que espera recibir JSON
  • User-Agent — identifica su cliente (algunas API lo requieren)
import requests

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-proj-abc123xyz',
    'Accept': 'application/json',
    'User-Agent': 'MyAgent/1.0'
}

response = requests.post(
    'https://api.example.com/analyze',
    headers=headers,
    json={'text': 'Analyze this document'}
)

print(response.json())

Cuerpo JSON de la solicitud y la respuesta

La mayoría de las API modernas intercambian datos en formato JSON. Al enviar datos, utilice json=payload en requests (serializa los datos y establece los encabezados automáticamente). Al recibirlos, llame a response.json() para analizar el cuerpo y convertirlo en un diccionario de Python.

Valide siempre que existan las claves esperadas antes de acceder a ellas.

import requests

# Send JSON body
response = requests.post(
    'https://api.example.com/summarize',
    json={
        'content': 'Long article text here...',
        'max_length': 150,
        'format': 'bullet_points'
    }
)

# Parse JSON response
result = response.json()

# Always check keys exist
summary = result.get('summary', 'No summary returned')
tokens_used = result.get('usage', {}).get('total_tokens', 0)

print('Summary:', summary)
print('Tokens used:', tokens_used)

Unir todas las piezas

Un agente bien escrito encapsula las llamadas a la API en una función auxiliar clara que selecciona el método, establece los encabezados adecuados, comprueba el código de estado y analiza el JSON. Esto hace que todas las interacciones con la API sean coherentes y fáciles de depurar.

Utilice un objeto Session para reutilizar conexiones y compartir encabezados entre varias solicitudes.

import requests

class APIClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        })

    def get(self, path, params=None):
        r = self.session.get(f'{self.base_url}{path}', params=params)
        r.raise_for_status()
        return r.json()

    def post(self, path, payload):
        r = self.session.post(f'{self.base_url}{path}', json=payload)
        r.raise_for_status()
        return r.json()

# Usage
client = APIClient('https://api.example.com', 'sk-proj-abc123')
tasks = client.get('/tasks', params={'status': 'open'})
new_task = client.post('/tasks', {'title': 'Write report'})

Comprobación rápida: métodos HTTP

Compruebe su comprensión de los métodos HTTP y los códigos de estado.

Resumen de los fundamentos de HTTP

Ya conoce los fundamentos de HTTP en los que se basa todo agente:

  • GET obtiene, POST crea, PUT/PATCH actualiza y DELETE elimina
  • 2xx = éxito, 4xx = error de su agente, 5xx = error del servidor
  • Los encabezados transportan la autenticación (Authorization: Bearer) y el formato (Content-Type: application/json)
  • Utilice response.json() para analizar el cuerpo y .get() para acceder a los campos de forma segura
  • Un objeto Session comparte encabezados y conexiones entre solicitudes

Con estos fundamentos claros, podrá conectar su agente a cualquier API REST con confianza.

Preguntas frecuentes

¿La lección «Fundamentos de REST API para desarrolladores de agentes» es gratis?

Sí — el texto completo de «Fundamentos de REST API para desarrolladores de agentes» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.

¿Qué aprenderé en «Fundamentos de REST API para desarrolladores de agentes»?

Métodos HTTP, códigos de estado, cabeceras y formato JSON de solicitudes y respuestas. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Agents?

No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Fundamentos de REST API para desarrolladores de agentes»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Agents?

Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Fundamentos de REST API para desarrolladores de agentes
  2. Autenticación: claves de API y OAuth
  3. Gestión de respuestas y errores de API
  4. Limitación de velocidad y lógica de reintentos
← Volver a AI Agents