Guías prácticas

Documente y pruebe una API de sus casos de uso

Una API útil permite que otro equipo entienda lo que puede solicitar y lo que recibirá. Su contrato debe ser comprobable, versionado y consistente con el servicio operativo.

Ver el método

Ilustración — Documente y pruebe una API de sus casos de uso
Ilustración generada por IA

Elija Tareas antes de direcciones

JavaScript: 9007199254740993 numérico se redondea; la cadena conserva cifras.
Ilustración · Demostración JSON.parse: Number redondea el token; String mantiene cifras. Acordar representación antes de convertir.

La lista de usos, como encontrar un producto, leer disponibilidad, actualizar un registro o un procesamiento de seguimiento. Definir personas y sistemas autorizados para cada operación. Una API de lectura pública y una API administrativa tienen diferentes requisitos de acceso.

Prepare un ejemplo de solicitud y respuesta para cada tarea esencial utilizando valores sintéticos y campos explicados. Distinguir identificadores estables, etiquetas, unidades y fechas. Defina los datos faltantes en lugar de sustituir los valores plausibles por información desconocida.

Defina cómo representar identificadores grandes en JSON. Con Number binary64 de JavaScript, los enteros de −9007199254740991 a 9007199254740991 están en el intervalo exacto de interoperabilidad de RFC 8259. 9007199254740992 es representable pero no seguro: el token vecino 9007199254740993 se redondea a 9007199254740992 al decodificar JSON con JavaScript estándar.

El identificador como cadena JSON conserva sus cifras. Acuerde el tipo entre productor, esquema y consumidor; convertir a texto un Number ya redondeado no recupera el original. Otras bibliotecas pueden conservar más precisión: pruebe los clientes admitidos. JSON válido no demuestra fidelidad y el tipo del identificador no debe cambiar silenciosamente.

Desplace la tabla horizontalmente para leer todas las columnas. Con el teclado, sitúe el foco en la tabla y use las flechas.

Decodificación JSON JavaScript: precisión y tipo
Token JSON de ejemploValor JavaScript mostradoInterpretación
90071992547409919007199254740991Entero seguro en el ejemplo
90071992547409929007199254740992Exacto, pero fuera del intervalo seguro
90071992547409939007199254740992Redondeado: se pierde la última cifra original
"9007199254740993""9007199254740993"Cadena exacta; tipo textual acordado

describir un contrato explícito

OpenAPI proporciona un formato de descripción independiente del idioma para las API HTTP, que cubre operaciones, parámetros, respuestas y modelos. Elija una versión admitida por sus herramientas y conserve el documento con el proyecto; La versión más reciente no es automáticamente el adecuado para cada cadena de herramientas.

Límites de uso de documentos, paginación, filtros, pedidos, errores y respuestas vacías. No trate los CORS como prueba de autorización. Revise los controles de operación y acceso a nivel de objeto con el equipo técnico.

Para una API ficticia de gestión de solicitudes, describa por separado las cuatro respuestas siguientes. En este contrato, 201 devuelve un recurso creado con su cabecera Location; 202 aporta una referencia de seguimiento porque el trabajo no ha terminado. No convierta cualquier respuesta 2xx en «operación terminada». El cliente debe leer el estado, las cabeceras y el modelo definido para la operación.

Una respuesta 204 no tiene cuerpo para decodificar como JSON. En este ejemplo, una instrucción sintácticamente correcta que infringe una regla de negocio recibe 422 con un problema estructurado en application/problem+json. Si se incluye el miembro status, su generador debe hacerlo coincidir con el estado HTTP real; el texto traducido de detail no debe ser la clave de decisión del programa. Documente identificadores estables del problema y la corrección esperada.

Desplace la tabla horizontalmente para leer todas las columnas. Con el teclado, sitúe el foco en la tabla y use las flechas.

Cuatro respuestas de una API ficticia y sus efectos en el cliente
Respuesta previstaHecho establecidoComprobación del consumidor
201 CreatedRecurso creadoComprobar Location exigido por este contrato y el identificador creado
202 AcceptedTratamiento aceptado, no terminadoConservar la referencia; esperar el resultado final
204 No ContentAcción completada sin cuerpo de respuestaNo intentar decodificar un cuerpo vacío como JSON
422 Unprocessable ContentInstrucción comprendida, pero no procesable según la reglaLeer el problema estructurado y ofrecer la corrección adecuada
  • RFC 9110 : HTTP Semantics

    RFC 9110, consultada el 22 de octubre de 2026: semántica de estados. Las respuestas y campos exigidos definen un contrato ficticio.

  • RFC 9457 : Problem Details

    RFC 9457, consultada el 22 de octubre de 2026: formato de problemas y función del miembro status.

Evitar que una modificación sobrescriba la de otro editor

  1. Dos lecturas de r7
  2. Primera escritura: r8
  3. Escritura antigua: 412
  4. Comparar antes de continuar

Caso ficticio: dos editores abren la ficha DEMO-17 con el ETag fuerte "r7". El primero guarda una corrección y la representación actual pasa a "r8". El segundo sigue trabajando sobre "r7". Una escritura condicional permite detectar la diferencia antes de sustituir la versión publicada.

En una API que admita este contrato, el cliente envía If-Match con el validador fuerte recibido. El servidor compara la versión antes de escribir: el ejemplo prevé 412 si ha cambiado. W/"r7" es débil y no satisface la comparación fuerte. If-Match: * comprueba la existencia de una representación actual, no que siga igual desde su lectura.

Conserve el borrador del segundo editor, lea la versión actual y muestre las diferencias antes de decidir un nuevo envío. Sustituir automáticamente el validador por "r8" y reenviar el borrador antiguo eludiría la protección. La comprobación y la escritura deben ser indivisibles en el almacenamiento; dos solicitudes concurrentes con el mismo validador no deben sobrescribir ambas la misma versión.

Este control no sustituye autenticación, permisos sobre la ficha ni validación de campos. Tampoco garantiza una única ejecución de una llamada externa. Compruebe estas propiedades por separado y documente las precondiciones ausentes; 428 permite exigir una solicitud condicional.

Desplace la tabla horizontalmente para leer todas las columnas. Con el teclado, sitúe el foco en la tabla y use las flechas.

Dos editores, una versión actual: secuencia ficticia de prueba
PasoVersión y solicitudResultado previsto en este contrato
Lectura de ambos editoresETag: "r7"Cada uno conserva el validador con su borrador.
Primer guardadoIf-Match: "r7" → versión "r8"Se conserva la corrección del primer editor.
Segundo guardado desactualizadoIf-Match: "r7"; versión actual "r8"412; no sustituir la corrección guardada.
Conciliación explícitaLeer "r8", comparar y decidirConservar el borrador y verificar permisos antes de otra escritura.

Test Límites y Permisos

Pruebe un objeto existente, un objeto faltante, un parámetro no válido y una lista de más de una página. Consulte la página siguiente para ver si hay pérdidas o repeticiones dentro del modelo de actualización elegido. Limitaciones de estado que la API no puede garantizar.

Utilice cuentas de prueba con diferentes permisos. Intente lecturas y cambios fuera del alcance permitido utilizando datos sintéticos. Registre los estados esperados y los mensajes útiles sin exponer trazas internas o secretos de configuración.

Plan de cambio y apoyo

distinguir un campo agregado de un campo eliminado o un significado cambiado. Identificar a los consumidores ante un cambio incompatible. Explique el período de transición y cómo detectar las integraciones que siguen utilizando el contrato anterior.

Entregue un ejemplo ejecutable para un entorno de prueba, una matriz de prueba y un contacto técnico. Relacionar los errores observados con ejemplos documentados después de la liberación. La documentación limitada al caso ideal deja a los integradores sin orientación para rechazos e interrupciones.

Documentación principal: Iniciativa OpenAPI : Especificación.

Documentos de referencia

Contenido actualizado

Referencias documentadas para este tema

Referencias documentadas para este tema
ReferenciaValor o sintaxisAlcance
RFC 8259 · JSON
application/json · UTF-8JSON estándar no admite comentarios ni comas finales; las cadenas usan comillas dobles.
RFC 3339 · Date-time
2026-10-22T09:00:00+02:00El desfase explícito relaciona la hora local con UTC; este ejemplo no es una cita.
HTTP · If-Match
If-Match: "r7" → 412If-Match compara un validador fuerte antes de escribir. En el contrato ilustrado, una versión antigua recibe 412; se conserva el borrador para comparar cambios.
HTTP · 428
428 · Precondition Required428 permite exigir una solicitud condicional. Su uso debe documentarse en el contrato; este estado no proporciona por sí solo un bloqueo.

Las fechas indican la consulta de las referencias. Estos datos no constituyen una auditoría ni una declaración global de conformidad.

Distinguir estado HTTP, JSON y resultado

Elija un intercambio ficticio y pruebe su lectura local. Éxito HTTP, JSON legible y operación terminada requieren comprobaciones distintas.

Los fragmentos son incompletos y usan direcciones de demostración. La prueba crea una Response en memoria: no contacta servidores ni simula red, caché o tratamiento de negocio.

200Una nueva representación completa
Qué significa
En este fragmento, el servidor responde al GET condicional con cuerpo JSON y validador demo-v2.
Qué comprobar
Compare If-None-Match, ETag y la revisión del cuerpo. El ensayo local analiza el JSON de este ejemplo.
Precaución
Un 200 no garantiza JSON válido ni datos de negocio correctos. Analizar este cuerpo no valida el esquema de sus propios datos.
Fragmento de intercambio ficticio
GET /demo/catalogue
If-None-Match: "demo-v1"

HTTP/1.1 200 OK
ETag: "demo-v2"
Content-Type: application/json

{"revision":"demo-v2"}

202Aceptado, tratamiento pendiente
Qué significa
202 indica aceptación para procesar, no finalización. El cuerpo ficticio muestra queued.
Qué comprobar
Conserve DEMO-42 y siga su estado según el contrato de la API, con permisos y límites de reintento.
Precaución
Response.ok es true. Ni ese valor ni un JSON legible prueban la finalización. Los campos y la dirección de seguimiento son convenciones ficticias.
Fragmento de intercambio ficticio
POST /demo/jobs

HTTP/1.1 202 Accepted
Location: /demo/jobs/DEMO-42
Content-Type: application/json

{"job":"DEMO-42","status":"queued"}

204Petición satisfecha, sin cuerpo
Qué significa
204 indica que el servidor satisfizo la petición sin contenido de respuesta. El fragmento no transmite JSON.
Qué comprobar
Gestione la ausencia de cuerpo según el contrato. Determine qué confirma el receptor antes de anunciar un resultado al visitante.
Precaución
Analizar JSON vacío falla aunque Response.ok sea true. En un webhook, puede confirmarse solo la recepción; las acciones posteriores requieren comprobación.
Fragmento de intercambio ficticio
POST /demo/events

HTTP/1.1 204 No Content

304Copia revalidada, sin cuerpo nuevo
Qué significa
304 responde a una petición condicional: puede reutilizarse la representación guardada. No aporta un cuerpo nuevo.
Qué comprobar
Compare el validador enviado con la copia demo-v2 disponible. La interpretación depende también de esa copia.
Precaución
La prueba crea una Response 304 aislada, no una caché HTTP. En un fetch real el navegador puede entregar la respuesta guardada: estado de red y estado visible al script pueden diferir.
Fragmento de intercambio ficticio
GET /demo/catalogue
If-None-Match: "demo-v2"

HTTP/1.1 304 Not Modified
ETag: "demo-v2"

Referencias técnicas : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

Matriz de validación funcional para adaptarse al proyecto

Estos controles propuestos utilizan casos ficticios. Decida qué comportamiento se espera con el equipo, anote el resultado y asigne discrepancias no resueltas antes de la publicación.

Desplace la tabla horizontalmente para leer todas las columnas. Con el teclado, sitúe el foco en la tabla y use las flechas.

Casos de prueba, resultados esperados y evidencia útil
CasoResultado esperadoPrueba para mantener
Recursos presentes y ausentesCada resultado coincide con el estado documentado y el modelo de respuesta.Solicitud, respuesta y ejemplo de contrato correspondiente capturado del entorno de prueba.
Parámetro fuera de rangoLa negativa es comprensible y no expone ningún rastro interno de pila.Mensaje público y resultado retenido en la matriz de aceptación.
Dos niveles de permisosUn recurso prohibido sigue siendo inaccesible incluso con un identificador conocido.Comparó resultados utilizando dos cuentas sintéticas con permisos explícitamente diferentes.
Paginación y filtro cambiadoSe definen el manejo de tokens y el comportamiento de reinicio del viaje.Pedidos, identificadores devueltos y reglas que se aplican cuando cambia el filtro.

Preguntas frecuentes

¿La documentación generada es suficiente para probar una API?

Ayuda a leer un contrato, pero los permisos, datos faltantes, errores, listas y cambios aún requieren pruebas. Compare ejemplos con respuestas reales de medio ambiente de prueba.

¿Cors reemplaza los permisos de acceso?

No. Las reglas de origen cruzado no reemplazan la operación y los permisos de objeto del servicio. Describa esos permisos y pruebe la aplicación del lado del servidor con cuentas de prueba.