Tiempo de lectura estimado : 8 min · Publicado
Elija Tareas antes de direcciones
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.
| Token JSON de ejemplo | Valor JavaScript mostrado | Interpretación |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Entero seguro en el ejemplo |
| 9007199254740992 | 9007199254740992 | Exacto, pero fuera del intervalo seguro |
| 9007199254740993 | 9007199254740992 | Redondeado: 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.
| Respuesta prevista | Hecho establecido | Comprobación del consumidor |
|---|---|---|
| 201 Created | Recurso creado | Comprobar Location exigido por este contrato y el identificador creado |
| 202 Accepted | Tratamiento aceptado, no terminado | Conservar la referencia; esperar el resultado final |
| 204 No Content | Acción completada sin cuerpo de respuesta | No intentar decodificar un cuerpo vacío como JSON |
| 422 Unprocessable Content | Instrucción comprendida, pero no procesable según la regla | Leer 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
- Dos lecturas de r7
- Primera escritura: r8
- Escritura antigua: 412
- 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.
| Paso | Versión y solicitud | Resultado previsto en este contrato |
|---|---|---|
| Lectura de ambos editores | ETag: "r7" | Cada uno conserva el validador con su borrador. |
| Primer guardado | If-Match: "r7" → versión "r8" | Se conserva la corrección del primer editor. |
| Segundo guardado desactualizado | If-Match: "r7"; versión actual "r8" | 412; no sustituir la corrección guardada. |
| Conciliación explícita | Leer "r8", comparar y decidir | Conservar el borrador y verificar permisos antes de otra escritura. |
- IETF · RFC 9110 § 13.1.1
IETF : Escrituras condicionales y precondiciones
- IETF · RFC 6585 § 3
428 · Precondition Required
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
- Iniciativa OpenAPI : Especificación · Fuente consultada
- IETF : RFC 8259: JSON numbers · Fuente consultada
- TC39 : Number.isSafeInteger · Fuente consultada
Contenido actualizado
Referencias documentadas para este tema
| Referencia | Valor o sintaxis | Alcance |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | JSON estándar no admite comentarios ni comas finales; las cadenas usan comillas dobles. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | El desfase explícito relaciona la hora local con UTC; este ejemplo no es una cita. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-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 Required | 428 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.
