Que esperar
El objetivo es mostrar a los desarrolladores qué problemas enfrentan sus usuarios de API en el ejemplo de trabajar con varios sistemas CRM.
Para proteger mi cara, no anunciaré los nombres de los participantes en este artículo.
Además, yo no soy un programador de la novia de mi madre, así que no tome mis conclusiones como la única opción verdadera.
Delineador de ojos
Érase una vez un niño esperanzado. Este niño no tenía nada en su vida excepto trabajar en el soporte técnico de programas de contabilidad. Cocinó en este caldero durante mucho tiempo, hasta que en un día, arrancó su techo, envió el rasgo principal del anfitrión y se fue en busca de perspectivas.
El niño siempre soñó con cómo se convertiría en un desarrollador genial, ganaría dinero extraordinario, preferiblemente en la moneda Basurm. Y, por lo tanto, en paralelo con el trabajo, se involucró en la creación de su sitio, utilizando tecnologías sin precedentes, pero con características desconocidas para esos años. Gracias a esto, pudo encontrar un nuevo propietario, que le dio un trabajo en su negocio favorito, con un buen salario y con perspectivas poco realistas.
Desde entonces, el niño vivió, vivió e hizo el bien. Y él no conocía los problemas y las penas ... ¿o lo sabía? ¡Vamos a resolverlo!
Conseguí un trabajo en una empresa de inteligencia empresarial. ¿Y qué tipo de análisis puede ser sin datos? Por lo tanto, la compañía tenía un equipo separado, y luego un departamento que se dedicaba a recopilar datos de los sitios de los clientes para crear programas de ingresos de canales de publicidad y otras fuentes. Hablando sobre los detalles, mi trabajo consistía en instalar nuestro contador en los sitios, recopilar datos sobre el visitante y crear aplicaciones a partir de formularios, chats en línea, devoluciones de llamada, etc. en sus sistemas de CRM. De los cuales, en el futuro, nuestros análisis obtuvieron información sobre el estado y el monto de la venta.
Y parece que no hay nada complicado aquí, dado que la creación de aplicaciones en CRM se simplificó envolviendo nuestro sistema, que, utilizando 1 solicitud, creó la aplicación y el cliente, incluida la responsabilidad de los servicios de terceros. Pero como debe entender, esa lógica no difiere en flexibilidad. Y si el cliente necesitaba algo no estándar, entonces ya era necesario "apagar el modo de confort" y ponerse las mangas para trabajar directamente con la API del sistema deseado. Y a veces, trabajando con la próxima API problemática,
creo que sería mejor permanecer en ellas. apoyo ...
Problema # 1: falta de métodos / datos
Quizás el problema más común que he encontrado en mi vida es la falta de la capacidad de obtener los datos que necesito en la interfaz. Los conflictos con los clientes surgieron constantemente y continúan surgiendo, debido al hecho de que no podemos obtener algo que ven en las pantallas de sus monitores todos los días.
Por ejemplo, hace un par de años, nos llegó un cliente bastante grande que necesitaba guardar en los archivos CRM que los clientes le envían desde los formularios en el sitio. Una tarea ordinaria, pero no había posibilidad de implementación, ¡y no hasta el día de hoy!
La falla para el cliente era inaceptable, y al final tuvimos que cargar archivos, emulando solicitudes JS desde la interfaz.
Debo decir que este CRM, autorización en la API, también autoriza en la interfaz, lo que, para mí, es una solución bastante extraña. Sin embargo, gracias a esto, no tuvimos que emular la autorización habitual. ¿O fue concebido ...?Otro caso con el mismo CRM sucedió no hace mucho tiempo. Era necesario responsabilizarse del administrador de aplicaciones que está actualmente activo. Y como ya entendió, la API no nos devuelve información sobre la actividad del administrador. Pero la paradoja es que su API JS regresa. Como resultado, tuve que escribir una aplicación JS, una especie de intermediario, con la que informaba al servidor sobre los administradores activos en este momento.
Solución:En nuestro equipo, es costumbre crear un método API público para la interfaz e interactuar con el servidor a través de él. Esto elimina el problema de desajuste entre las capacidades técnicas de la interfaz y la API pública.
Problema número 2: la falta de un estilo uniforme de solicitudes / respuestas
Un problema muy común incluso en grandes CRM occidentales. Supongamos que necesitamos obtener una lista de pedidos durante un mes, descubrimos que el sistema tiene un límite en la cantidad de elementos en la carga. Y para navegar por las páginas necesita usar el parámetro offset. Bien, hemos implementado el método de carga de pedidos y, por separado, el método auxiliar de paginación.
Ahora, necesitamos descargar la lista de clientes, estamos implementando un nuevo método junto con el método de paginación escrito anteriormente, y ... Obtenemos un error. Debido a que PM y los desarrolladores decidieron que el desplazamiento suena demasiado fácil, ahora dejemos que sea offset de video.
Por supuesto que exagero, no puedo saber qué pasó cuando escribieron esta API. Pero esto es al menos un error de PM, porque no especificó cómo ya se implementó en otros métodos. Y también un error de los desarrolladores, los que escribieron un nuevo método y los que fueron verificados. Por ahora, todos los que usan su API se ven obligados a construir muletas en sus aplicaciones.
Solución:Cualquier nuevo método api, si es posible, debe corresponder a la estructura de los existentes. El líder técnico (o el líder del equipo por falta del primero) puede elaborar una regulación, una especie de estilo de código, según el cual es necesario desarrollar una API, y sin falta familiarizar a todos los desarrolladores con ella. Si el problema ya tiene un lugar para estar, entonces, si es posible, es mejor poner una muleta de su lado que obligar a miles de sus clientes a hacerlo de su lado.
Problema número 3: documentación deficiente o falta de ella
La documentación es una referencia del desarrollador. A menudo nos encontramos con situaciones en las que se nos pregunta sobre la posibilidad de implementar una característica en particular. Y si no recordamos o no sabemos la respuesta, abra inmediatamente la documentación. Encontrar información en un buen directorio es trabajar durante un par de minutos, mientras que en uno sobrecargado puede excavar durante media hora, y aún así no obtendrá una respuesta definitiva.
En algunos casos avanzados, es simplemente imposible de encontrar en el dominio público. Y si necesita obtener una lista actualizada de métodos, debe ponerse en contacto con el soporte técnico. Y luego aún debe verificar si algo nuevo apareció allí, que le preguntamos a un par de clientes ...
Solución:Daré algunos puntos que, en cuanto a mí, caracterizan la documentación de calidad:
- buscar por nombre, descripción y parámetros del método
- descripción correcta del propósito del método
- lista de parámetros aceptados con tipo y descripción
- lista de parámetros devueltos con tipo y descripción
- solicitar ejemplo
- ejemplo de respuesta
- posibles códigos de error con una descripción
- un sandbox en el que puedes "jugar" con solicitudes en modo de diseño
- cambiar el historial de todos los métodos de la API para una referencia rápida
Problema número 4: bicicletas de autorización
Conoces esta sensación maravillosa cuando abres la documentación de un nuevo sistema, y allí, en la sección de autorización, se describe un pedido de 3 métodos para obtener una clave válida para solo 1 solicitud ...? Entonces, no lo tengo.
Para mí sigue siendo un misterio por qué los desarrolladores abandonan Oauth 2.0 en favor de sus bicicletas. Y bueno, si la autorización se limita a un token constante, pero aquí está toda la cadena de autorización ...
Solución:No debe reinventar su bicicleta cuando ya hay estándares prefabricados. De hecho, para estos estándares, los desarrolladores ya tienen sus propios componentes para una autorización simple.
Epílogo
Hablé sobre 4 problemas que encontré al comienzo de mi viaje hasta el día de hoy. Traté de proporcionar sus soluciones, pero tú decides si son buenas o no. Al final, cada uno de nosotros tiene nuestra propia arquitectura de pensamiento.
Entonces, ¡agradezco a todos los que han leído hasta ahora! Este es mi primer artículo, y si tuviera un valor informativo para usted, me alegraría continuar con la serie de artículos sobre mi sufrimiento con la API.
Y, por supuesto, me alegrará escuchar las opiniones de expertos en los comentarios.
¡Todo con el próximo 2020!