Durante un año y medio, integramos API con veinte servicios externos. Las primeras cinco integraciones pasaron por el dolor y las lágrimas: cometimos todos los errores posibles. Reescribieron el código varias veces, se separaron de los socios justo antes del lanzamiento, porque no podían ponerse de acuerdo sobre las mejoras. Tiempo perdido y dinero.
Pero con cada nueva integración, encontramos soluciones para problemas recurrentes. Como resultado, hicimos la última integración cuatro veces más rápida que la primera. Lo que ahora hacemos de manera diferente: lea el artículo.
Para que comprenda mejor los detalles de nuestras integraciones, describiremos brevemente lo que hacemos. Estamos desarrollando un corredor en línea. Principio de trabajo: el usuario llega al sitio, completa el cuestionario, lo transferimos a las organizaciones de microfinanzas (IMF) y recibimos la aprobación o el rechazo de un préstamo. El usuario selecciona una oferta adecuada y recibe dinero. Para que esto funcione en línea, nos integramos con las IMF a través de API.
Evaluar la preparación de los socios para la integración mediante una lista de verificación y especificaciones
Analizaremos dos escenarios: cuando un socio potencial ya tiene una API para aceptar aplicaciones, y cuando no. Ambos escenarios sugieren que el socio desea integrarse con nosotros y está listo para pasar tiempo en esto.
El socio no tiene API: enviamos la especificación
Anteriormente, le explicamos al socio, verbalmente o por correspondencia, lo que necesitábamos para la integración, y el socio basado en estas explicaciones hizo una API para aceptar aplicaciones con Finspin. No acordamos los requisitos para los modelos, objetos, campos del cuestionario y las reglas para su validación. Describió rápidamente el propósito de los métodos y las posibles respuestas. El resultado resultó estar infinitamente lejos de lo esperado, porque nuestra comprensión de la API era muy diferente de la asociación. Tuve que rehacer todo.
Ahora Escribimos nuestra especificación: un archivo YAML que se puede abrir en Swagger. En la especificación, describimos la API más adecuada para integrar Finspin con las IMF: campos de cuestionarios y reglas para su validación, formatos y tipos de solicitudes con respuestas, nombres de métodos, posibles errores y estados. Registramos el estado del estado de la solicitud que planeamos recibir, por ejemplo: "aceptado para procesamiento", "puntuación en progreso", "préstamo denegado", "aprobación", etc.
Enviamos la especificación al socio, y él decide si puede proporcionar dicha API. Si no puede, observa puntos problemáticos en la especificación, por ejemplo, no todos los estados de la aplicación están listos para ser transferidos a la API o no hay suficientes campos en el cuestionario. Y ya estamos discutiendo puntos específicos, no entidades abstractas. El socio no pierde el tiempo escribiendo su documentación, sino que ajusta la nuestra.
Pasamos dos días creando la especificación, pero ahora estamos ahorrando decenas de horas en aprobaciones y mejoras a la API. Además, con la ayuda de las especificaciones, filtramos rápidamente a los socios que no están listos para la integración. En las primeras etapas, queda claro que nuestros procesos de procesamiento de solicitudes en línea son muy diferentes: no es rentable integrarlos.
El socio tiene una API: ejecuta la lista de verificación
Solíamos obtener las especificaciones de un socio y hacer preguntas sobre la marcha. A menudo se olvidaron de aclarar algo importante, y luego este importante surgió en las etapas finales de desarrollo y prueba, cuando se volvió especialmente costoso arreglarlo y reescribirlo. De alguna manera, al final de la integración con un socio, resultó que transferiría el estado de los préstamos a través de API con un retraso de varios días. Para nosotros, esto es inaceptable. La sociedad tuvo que ser abandonada.
Ahora Hemos escrito una lista de verificación para evaluar la API y los procesos que sirve. La lista de verificación recopiló preguntas que deben ser respondidas. Primero, nuestro gerente busca respuestas en la especificación. Si no se encuentra, dirige las preguntas al socio.
La lista de verificación ayuda a encontrar cuellos de botella antes del inicio del desarrollo, y no después, cuando tiene que editar el código y los clientes sufren debido al mal servicio.
Reabastecemos constantemente la lista de verificación cuando nos enfrentamos a nuevas situaciones. Cuanto más detallada sea la lista de verificación, menor será el riesgo de omitir errores en el desarrollo.
Fragmento de lista de verificación de APIGlosario de Términos
Anteriormente, nos parecía que en el campo de los préstamos en línea todos entienden los términos profesionales de la misma manera, no puede haber discrepancias. La práctica ha demostrado que estábamos equivocados.
Por ejemplo, con una IMF, interpretamos a los clientes primarios y repetidos de manera diferente. Para nosotros, el cliente principal es el cliente cuyo perfil ingresó por primera vez a la base de datos de MFI a través de Finspin, y el cliente habitual ya estaba en la base de datos. El socio consideró a los clientes que repiten por el número de préstamos emitidos: repitió recibió dos préstamos y obtuvo un tercero. Tal confusión terminológica podría conducir a inconsistencias en las conciliaciones financieras.
Ahora usamos un pequeño glosario de términos por el cual verificamos con los socios. Como regla, es suficiente aclarar cinco o seis términos básicos para sincronizar ideas sobre integración y evaluar las perspectivas de colaboración.
Una vez que un glosario de términos nos ha ayudado a evitar una integración desventajosa. Nuestra interpretación de "aprobación" fue muy diferente de la del afiliado. La "aprobación" del socio incluyó muchos aspectos diferentes que requerían procesamiento manual. Nos esforzamos por lograr la máxima automatización, por lo que inmediatamente nos negamos a cooperar.
Aclarar el término "aprobación"Primero negocios, luego desarrollo
Solía haber casos en los que comenzamos a trabajar con un socio potencial con una especificación. Nuestro gerente recibió la especificación, la estudió cuidadosamente, aclaró con los detalles del socio para la integración, discutió los problemas en disputa con los desarrolladores. Y luego llegó un mensaje del liderazgo: "Fin, la integración se cancela, no estábamos de acuerdo con las condiciones". Los empleados perdieron el tiempo.
Cuando cambias de opinión y el trabajo está hechoAhora la regla de hierro
está vigente: el gerente comienza a estudiar la especificación solo cuando recibe una decisión clara sobre la integración de la administración.
Disponibilidad para la integración: URL, detalles, entorno
Anteriormente, la primera llamada a la API del socio ocurrió durante la prueba de nuestra aplicación, desde servidores de desarrollo. A menudo, las primeras solicitudes reciben errores en la etapa de configuración de la conexión: no se puede conectar al servidor o simplemente se agota el tiempo de espera. Razones más populares:
- Nombres de métodos incorrectos (sellados o confusos)
- Dominio inválido
- detalles de conexión erróneos,
- No agregamos la IP de nuestros servidores a la lista blanca.
Se necesitaron horas para solucionar estos errores menores, porque se sucedieron uno tras otro: hasta que solucione uno, no verá el siguiente.
Ahora , antes de llevar la tarea al plan de desarrollo, aclaramos todas las características de acceso a la API con una pequeña lista de verificación. La lista de verificación enumera los puntos que deben aclararse, por ejemplo:
- restricciones en la carga del servicio,
- el número de solicitudes por unidad de tiempo
- detalles de conexión
- lista blanca por direcciones ip,
- Validación de certificado SSL
- requisitos de encriptación del tráfico,
- encabezados especiales en solicitudes
- la presencia de un servidor de prueba con API o la capacidad de enviar solicitudes de prueba al servidor de combate
Si hay una API de prueba, definitivamente descubriremos cuál es la diferencia al acceder al servidor de batalla y al servidor de prueba. Tenemos en cuenta las diferencias al crear solicitudes de nuestra aplicación a socios en entornos de desarrollo y producción. Dichas medidas nos ayudan a comprender si los sistemas están listos para nuestras necesidades o si se necesitan ajustes adicionales.
Envío manual de solicitudes a la API
Antes, escribimos de inmediato el código de acuerdo con las especificaciones del socio, elaboramos las especificaciones, revisamos, probamos. Y en la etapa de las pruebas de integración, resultó que no todo lo escrito en la especificación corresponde a la realidad, comenzando desde el formato de las solicitudes, terminando con el proceso de pasar la aplicación.
Por ejemplo, de acuerdo con la especificación, al acceder a un determinado método, esperamos una respuesta en un cierto formato en la respuesta, colgamos el procesamiento para la validez de la respuesta recibida, vamos a las pruebas y de repente obtenemos una matriz en la respuesta. Descubrimos los motivos de los desarrolladores del socio. Se refieren a documentación obsoleta. Una vez más, un círculo de mejoras, revisiones y pruebas.
Ahora , tan pronto como recibimos la documentación y los detalles de la conexión, ejecutamos el proceso a través del cliente API. Por lo general, el probador carga la especificación a Postman y simula el proceso comercial completo de enviar una solicitud de préstamo, verifica los casos más populares con diferentes conjuntos de datos para la solicitud. Es decir, hace manualmente lo que hará la aplicación.
En la etapa de una ejecución manual, se revela el 80% de las imprecisiones en la documentación. Describimos los errores y pasamos al socio. El socio elimina las imprecisiones en el hogar o finaliza la especificación. Como resultado, para cuando comienza el trabajo en el código, los desarrolladores reciben documentación de trabajo.
Discrepancias más populares:
- formato de solicitud incorrecto, promete aceptar json, resultó que necesitaba datos de formulario;
- Errores en los nombres de los campos que se transmitirán en la solicitud;
- errores en formatos de campo;
- las reglas de validación de campo no se especifican o se indican incorrectamente;
- algunos campos pueden olvidarse por completo;
- falta o es diferente de la descripción real del formato de respuesta del método;
- marcas erróneas sobre los campos obligatorios: pueden aparecer "asteriscos" donde el campo no es obligatorio, y viceversa;
- a menudo no se documentan todos los estados y estados en los que puede estar el objeto;
- discrepancias entre los estados esperados y recibidos de los objetos. Por ejemplo, en algún momento, esperamos que la aplicación esté en estado X y, de hecho, según la API, obtenemos Y.
Receta para la felicidad: evitar errores de integración de API
Escriba una especificación para la integración con su servicio. Pasamos dos días desarrollando la especificación en YAML, pero ahora estamos ahorrando decenas de horas en mejoras y aprobaciones.
Si el socio envía su especificación, verifíquela en la lista de verificación. En la lista de verificación, recopile preguntas a las que debe recibir respuestas. No confíes en la experiencia y la memoria, aún te falta algo.
Tenga un glosario de términos para evitar confusiones con su pareja. Nuestra experiencia ha demostrado que las diferencias pueden ser incluso obvias.
No lleve la tarea al desarrollo hasta que reciba la aprobación de principios de la gestión de integración con un socio. La idea es obvia, pero nos ayuda a evitar el trabajo innecesario.
Abra una lista de verificación para aclarar los detalles específicos de acceso a la API del socio: detalles de conexión, lista blanca, validación de certificados SSL, requisitos de cifrado de tráfico, etc. Verifique la lista de verificación lo antes posible para evitar el deslizamiento en las etapas finales.
Obtuve una especificación: no se apresure a escribir código de inmediato. Primero, ejecute manualmente el proceso a través de un cliente API, por ejemplo, a través de Postman. Por lo tanto, encontrará errores en la especificación en una etapa temprana y con pequeños recursos. Y lo serán.