Documente y pruebe una API de sus casos de uso

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.

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.

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.