
Documento de diseño técnico breve – plantilla Google Docs
Docs + Word6 páginas
Gratis
Quien se une a un equipo de API necesita una solicitud que funcione en minutos, no una semana de lectura. Esta guía describe la colección compartida del equipo: cómo importar el archivo JSON al espacio de trabajo, qué entorno seleccionar y cómo se superponen los valores, desde los predeterminados compartidos hasta las claves personales. El ejemplo documenta una API de facturación e incluye un comando de shell para importar, una solicitud y su respuesta para crear una factura en borrador, y una lista de solicitudes agrupadas por recurso, como los pedidos. También explica cómo autenticarse con una clave personal.
Adapta el ejemplo cambiando la URL base, los grupos de recursos y los cuerpos de muestra para que coincidan con tu servicio. Deja en la colección los valores comunes, como los tiempos de espera, y reserva las claves de API para un entorno personal que nunca se exporte, de modo que nadie suba un secreto al archivo compartido. Primero ejecuta la importación en modo de prueba, revisa la lista de solicitudes y envía una llamada de solo lectura antes de cualquiera que modifique datos. Acompaña la guía con la colección para que cada paso tenga su solicitud.
Haz tu copia de la guía de colección desde Google Docs; tras el mensaje de Google, ya está en tu Drive.
Escribe tus URL base y tus solicitudes en lugar de las ficticias de Ravenmoor.
Quita todas las claves de los ejemplos y remite a quien lea al almacén de secretos.
Prueba cada ejemplo en staging antes de compartir la colección.
Borra la página de ayuda; después comparte la colección o preséntala desde Google Docs.
Es un conjunto guardado de llamadas a una API, cada una con su método, URL, encabezados y cuerpo de ejemplo, agrupadas por recurso. Los equipos comparten una para que los nuevos desarrolladores envíen solicitudes que funcionan sin escribirlas desde cero. La mayoría de las herramientas exportan la colección como archivo JSON que cualquiera puede importar. También puede incluir entornos, de modo que la misma solicitud apunte a valores locales, de staging o de producción.
Deja las claves fuera del archivo compartido. Guarda en la colección los valores comunes, como la URL base y los tiempos de espera, y que cada desarrollador agregue su clave personal en un entorno que nunca se exporte. Si una clave llegó a subirse al repositorio, revócala y genera otra. Usa claves de prueba en staging y busca secretos en el archivo exportado antes de enviarlo a un contratista.
En ambos, enlazados. La colección contiene las solicitudes que se pueden ejecutar; el documento explica el orden a seguir, la configuración de entornos y los pasos de autenticación. Mantén el documento breve y actualiza su nota de versión cuando cambie la API. La colección enlazada sigue siendo la fuente de verdad sobre los detalles de cada solicitud.
Más plantillas de Google Docs (en inglés)Más plantillas de flujos de desarrollo

Docs + Word6 páginas
Gratis
Docs + Word8 páginas
Gratis
Docs + Word7 páginas
Gratis
Docs + Word10 páginas
Gratis
Docs + Word10 páginas
Gratis
Docs + Word10 páginas
Gratis
Slides + PowerPoint10 diapositivas
Gratis
Docs + Word9 páginas
Gratis
Docs + Word9 páginas
Gratis
Slides + PowerPoint10 diapositivas
Gratis