{"id":34354,"date":"2019-10-31T21:57:51","date_gmt":"2019-10-31T18:57:51","guid":{"rendered":"https:\/\/prohoster.info\/blog\/pisali-api-porvali-xml-dva\/"},"modified":"2019-10-31T21:57:51","modified_gmt":"2019-10-31T18:57:51","slug":"pisali-api-porvali-xml-dva","status":"publish","type":"post","link":"https:\/\/prohoster.info\/es\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"Escribimos API \u2014 rompimos XML (dos)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

La primera API de Mi Almac\u00e9n apareci\u00f3 hace 10 a\u00f1os. Durante todo este tiempo hemos estado trabajando en las versiones existentes de la API y desarrollando nuevas. Ya hemos enterrado varias versiones de la API. <\/p>\n

En este art\u00edculo encontrar\u00e1s mucho: c\u00f3mo se cre\u00f3 la API, por qu\u00e9 es necesaria para los servicios en la nube, qu\u00e9 beneficios ofrece a los usuarios, en qu\u00e9 tropiezos hemos ca\u00eddo y qu\u00e9 queremos hacer a continuaci\u00f3n.
\n<\/a><\/noindex>
\nMe llamo Oleg Alekseev oalexeev<\/a><\/noindex>, soy el director t\u00e9cnico y cofundador de Mi Almac\u00e9n. <\/p>\n

\u00bfPor qu\u00e9 hacer una API para el servicio?<\/h2>\n

\nNuestros clientes, que son decenas de miles de emprendedores, utilizan activamente soluciones en la nube: banca, tiendas en l\u00ednea, gesti\u00f3n de inventarios, CRM. Se conectan a una, y ya es dif\u00edcil detenerse. Y as\u00ed, el quinto, octavo, d\u00e9cimo servicio facilita el trabajo del emprendedor, pero los datos entre estos servicios en la nube los usuarios los trasladan manualmente. El trabajo se convierte en una pesadilla.<\/p>\n

La soluci\u00f3n obvia es dar a los usuarios la posibilidad de transferir datos entre servicios en la nube. Por ejemplo, importar y exportar datos como archivos, que luego se pueden cargar en el servicio necesario. Los archivos generalmente se modifican seg\u00fan el formato de cada servicio. Esto es un trabajo manual m\u00e1s o menos simple, pero a medida que aumenta la cantidad de estos servicios, se vuelve cada vez m\u00e1s dif\u00edcil realizarlo.<\/p>\n

Por lo tanto, el siguiente paso es la API. Con ella, el servicio en la nube se beneficia al conectar varios servicios en un solo punto. La aparici\u00f3n de un ecosistema as\u00ed atrae nuevos clientes gracias a las capacidades adicionales. Un producto con nuevas funcionalidades se vuelve m\u00e1s rentable y \u00fatil.<\/p>\n

Si se crean interfaces de programaci\u00f3n propias, esto atrae a vendedores externos en forma de programadores que conocen su producto gracias a la API. Comienzan a construir soluciones basadas en la API ofrecida y ganan dinero automatizando las tareas de sus clientes.<\/p>\n

El sistema de contabilidad de Mi Almac\u00e9n se basa en procesos simples. Lo principal es trabajar con documentos primarios, poder recibir y enviar mercanc\u00edas, obtener informes basados en los documentos primarios para el negocio. Tambi\u00e9n hay transferencia de datos, por ejemplo, a la contabilidad en la nube, y su obtenci\u00f3n de sistemas bancarios o puntos de venta. Adem\u00e1s, trabajamos con tiendas en l\u00ednea: obtenemos informaci\u00f3n sobre productos y enviamos datos sobre existencias.<\/p>\n

\"Escribimos
\n<\/p>\n

La primera API de Mi Almac\u00e9n<\/h2>\n

\nA lo largo de los 10 a\u00f1os de trabajo de Mi Almac\u00e9n con la API, hemos acumulado diversas integraciones que permiten intercambiar datos, trabajar con bancos, realizar pagos y utilizar telefon\u00eda externa.<\/p>\n

En el primer a\u00f1o, habilitamos la posibilidad de exportar cualquier dato en formato XML. En ese entonces, a los usuarios les resultaba mucho m\u00e1s comprensible y habitual mantener los datos de manera offline, en lugar de en una nube, y les proporcionamos eso. La exportaci\u00f3n se iniciaba mediante una exportaci\u00f3n manual desde la interfaz. As\u00ed que no se pod\u00eda llamar API en ese momento. <\/p>\n

Ese mismo a\u00f1o comenzamos a colaborar con la empresa Rusagro: ellos ya utilizaban un ERP 'maduro' para la planificaci\u00f3n de producci\u00f3n y ventas, mientras que en Mi Almac\u00e9n automatizamos la carga de vagones en las f\u00e1bricas. As\u00ed tuvimos los primeros indicios de una API real: el intercambio entre nuestro servicio y el ERP se realizaba al enviar un gran archivo con datos sobre todos los tipos de documentos. <\/p>\n

Esta era una buena opci\u00f3n para el intercambio de datos por lotes, pero junto con los documentos, era necesario transmitir sus dependencias: informaci\u00f3n sobre productos, contrapartes y almacenes. Este tipo de acumulaci\u00f3n no es dif\u00edcil de generar en la exportaci\u00f3n, pero resulta bastante complicado desglosar en la importaci\u00f3n, ya que en un \u00fanico paquete llegan todos los datos: tanto sobre nuevos documentos como sobre los ya existentes.<\/p>\n

La primera API XML no dur\u00f3 mucho: despu\u00e9s de dos a\u00f1os comenzamos su reconstrucci\u00f3n. Desde el inicio de su funcionamiento cometimos varios errores al construir la interfaz de programaci\u00f3n.<\/p>\n

\"Escribimos
\nAs\u00ed se cre\u00f3 la API XML: ilustraci\u00f3n de uno de nuestros arquitectos. Por cierto, esperen sus art\u00edculos.<\/i><\/p>\n

Estos son nuestros principales errores:<\/p>\n

    \n
  1. La marcaci\u00f3n JAXB se realiz\u00f3 directamente sobre los entity beans. Para comunicarnos con la base de datos utilizamos Hibernate, y sobre esos mismos beans se hizo la marcaci\u00f3n JAXB. Este error se evidenci\u00f3 casi de inmediato: cualquier actualizaci\u00f3n en la estructura de datos requer\u00eda una urgente notificaci\u00f3n a todos los que utilizan la API, o la construcci\u00f3n de parches que garantizaran la compatibilidad con la estructura de datos anterior.<\/li>\n
  2. La API surgi\u00f3 como un complemento y, al principio, no definimos qu\u00e9 parte del producto representaba. No consideramos si la API era algo importante ni si deb\u00edamos mantener la compatibilidad hacia atr\u00e1s para sus primeros clientes. En un momento, el n\u00famero de usuarios de la API representaba alrededor del 5% del peque\u00f1o n\u00famero total, y no se les prest\u00f3 atenci\u00f3n. La filtraci\u00f3n universal que se llev\u00f3 a cabo en su momento llev\u00f3 a que nos comenzaran a usar como backend. Esta filtraci\u00f3n no era exactamente GraphQL, sino algo parecido: funcionaba a trav\u00e9s de una gran cantidad de par\u00e1metros en la cadena de consulta. Con una herramienta tan poderosa, a los usuarios les result\u00f3 dif\u00edcil resistirse, y comenzaron a enviar solicitudes directamente desde la interfaz de usuario de sus tiendas en l\u00ednea. La situaci\u00f3n se convirti\u00f3 en una desagradable sorpresa, ya que ofrecer tal servicio deber\u00eda requerir un esquema de precios diferente y una comprensi\u00f3n completamente distinta de la API como producto.<\/li>\n
  3. Debido a que la API no se desarroll\u00f3 como producto principal, la documentaci\u00f3n de la API se elabor\u00f3 y public\u00f3 de manera residual, a trav\u00e9s de ingenier\u00eda inversa. Este camino parece bastante simple y conveniente, pero contradice el trabajo contractual. Esto es cuando hay un componente con un esquema de funcionamiento preestablecido. El desarrollador lo implementa de acuerdo con este esquema y la tarea, el componente pasa pruebas, el cliente recibe un producto que coincide con la idea del analista. La ingenier\u00eda inversa, por otro lado, lanza al mercado un producto que simplemente existe: con parches, soluciones extra\u00f1as y bicicletas en lugar de la funcionalidad necesaria. <\/li>\n
  4. Todo el flujo de solicitudes que llegaba a trav\u00e9s de la API solo pod\u00eda ser analizado como un registro de Nginx o del servidor de aplicaciones. Esto no permit\u00eda identificar \u00e1reas espec\u00edficas, salvo dividir por usuarios y suscriptores. Si no hay forma de regular el registro de aplicaciones o clientes, se vuelve imposible analizar la situaci\u00f3n. Este problema afect\u00f3 en menor medida el desarrollo de la API; se trata m\u00e1s de entender su demanda y el contenido funcional que ofrece.<\/li>\n<\/ol>\n

    <\/p>\n

    Intento n\u00famero dos: REST API<\/h2>\n

    \nEn 2010, intentamos construir un sistema de intercambio con la contabilidad en l\u00ednea \u2014 BuchSoft. No funcion\u00f3. Sin embargo, durante el proceso de integraci\u00f3n, se desarroll\u00f3 una API completa: un servicio REST de intercambio, donde no hab\u00eda libertades como las llamadas a operaciones en forma de invocaciones RPC. Toda la comunicaci\u00f3n con la API se ajust\u00f3 al modo est\u00e1ndar para REST: en la cadena de solicitud se incluye el nombre de la entidad, y la operaci\u00f3n que se realiza con ella se establece mediante el m\u00e9todo HTTP. A\u00f1adimos filtrado por el momento de actualizaci\u00f3n de entidades, y ahora los usuarios tienen la posibilidad de construir replicaci\u00f3n con sus sistemas.<\/p>\n

    Ese mismo a\u00f1o, se lanz\u00f3 la API para la exportaci\u00f3n de existencias y mercanc\u00edas. A trav\u00e9s de la API, las partes m\u00e1s valiosas del sistema se hicieron accesibles para los usuarios: el intercambio de documentos primarios y los datos de c\u00e1lculo sobre existencias y costos de las mercanc\u00edas.<\/p>\n

    En diciembre de 2015, RetailCRM public\u00f3 la primera biblioteca de tercero para acceder a nuestra API. Esta se empez\u00f3 a utilizar de manera bastante activa, y al mismo tiempo creci\u00f3 la popularidad del servicio en general, la carga en la API aument\u00f3 m\u00e1s r\u00e1pido que la carga en la interfaz web. Una vez, el crecimiento se convirti\u00f3 en un salto de carga. <\/p>\n

    \"Escribimos
    \n
    \n\"Escribimos
    \n
    \nY este salto, al que apunta la flecha de la izquierda, dej\u00f3 completamente asombrado al servidor que atiende nuestra API. Pasamos una semana averiguando qu\u00e9 generaba exactamente esa carga. Result\u00f3 que eran esas mismas solicitudes que se transmit\u00edan a nuestra API desde los frontales de los clientes. Alrededor de 50 clientes fueron responsables. En ese momento entendimos uno de nuestros errores: la total ausencia de l\u00edmites. <\/p>\n

    Como resultado, introdujimos un l\u00edmite en el n\u00famero de solicitudes simult\u00e1neas. Desde una cuenta, ahora se pueden abrir no m\u00e1s de dos solicitudes al mismo tiempo. Esto es suficiente para trabajar en modo de replicaci\u00f3n para el intercambio de datos en modo por lotes. Aquellos que quer\u00edan utilizarlo como backend, a partir de ahora, tendr\u00edan que ajustarse m\u00e1s a las tarifas, ya que introdujimos el uso de m\u00faltiples cuentas en sus herramientas de software.<\/p>\n

    Ordenando<\/h2>\n

    \nDesde 2014, la demanda de la API existente se convirti\u00f3 en una parte importante del negocio, y la propia API generaba el mayor volumen de datos en el intercambio de informaci\u00f3n con los clientes. En 2015, lanzamos un proyecto para poner en orden la API. Elegimos el formato JSON en lugar de XML y comenzamos a construirlo sobre la base de las caracter\u00edsticas que identificamos al implementar la versi\u00f3n anterior:<\/p>\n

      \n
    1. La capacidad de gestionar versiones. La versionado permite desarrollar una nueva versi\u00f3n sin afectar la aplicaci\u00f3n existente ni interrumpir a los usuarios. <\/li>\n
    2. La posibilidad de que el usuario vea los metadatos en la respuesta que recibe.<\/li>\n
    3. La posibilidad de intercambiar grandes documentos. Si procesamos un documento con m\u00e1s de 4-5 mil \u00edtems, esto se convierte en un problema para el servidor: transacciones largas, solicitudes http largas. Se construy\u00f3 un mecanismo especial que permite actualizar documentos en partes y gestionar \u00edtems individuales de ese documento, envi\u00e1ndolos al servidor.<\/li>\n
    4. Herramientas para la replicaci\u00f3n \u2014 estaban en la versi\u00f3n anterior.<\/li>\n
    5. L\u00edmites de carga \u2014 como legado de los errores cometidos en la versi\u00f3n anterior. Se introdujeron l\u00edmites en el n\u00famero de solicitudes en un periodo de tiempo, el n\u00famero de solicitudes paralelas y solicitudes desde una misma direcci\u00f3n IP.<\/li>\n<\/ol>\n

      \nDesde entonces hemos lanzado dos versiones menores de la API y hemos puesto en marcha varias APIs especializadas, pero en general el enfoque ha permanecido sin cambios. El formato de intercambio actualizado y la nueva arquitectura han permitido corregir las deficiencias de la API mucho m\u00e1s r\u00e1pido.<\/p>\n

      API de MiAlmac\u00e9n hoy<\/h2>\n

      \nHoy, la API de MiAlmac\u00e9n resuelve muchas tareas:<\/p>\n