Haga que las retiradas de la versión de API no sean operativas ☁️

Esta es una traducción que desde EGA Futura ofrecemos como cortesía a toda la Ohana y comunidad de programadores , consultores , administradores y arquitectos de Salesforce para toda Iberoamérica .

El enlace a la publicación original, lo encontrarás al final de este artículo.

…

Salesforce ha sido durante mucho tiempo un pionero en el ámbito de las API, y la empresa está acreditada como uno de los inventores de la API web en 2000.

Las API web aparecieron por primera vez en la naturaleza con la introducción de Salesforce el 7 de febrero de 2000 cuando la compañía lanzó oficialmente su API en la conferencia IDG Demo 2000.

– API Evangelista

Desde entonces, las especificaciones y el consumo de API se han disparado. Con esta rápida evolución surgió la cuestión de la compatibilidad con versiones anteriores: ¿cómo puede ofrecer innovación al mismo tiempo que admite aplicaciones más antiguas? En esta publicación, presentaremos el plan de Salesforce para el retiro de API heredado. Proporcionaremos recursos, como un script de utilidad e instrucciones, para ayudarlo a identificar si se ve afectado o no. Obtendrá consejos sobre cómo actualizar integraciones que utilizan API heredadas y orientación sobre cómo planificar el futuro.

Planificar la retirada de la API heredada

Salesforce ha mantenido una de las posturas de compatibilidad con versiones anteriores más sólidas de la industria. Por ejemplo, la versión 7.0 de Salesforce SOAP API se lanzó en 2006: ¿qué estaba haciendo hace 15 años? No podría haber estado hablando en un iPhone, tocando en un iPad, escribiendo código en Python 3.0, ejecutando JavaScript en Node.js o llamando a un Uber, ¡ porque ninguna de esas tecnologías existía en ese entonces!

Dar soporte a las API heredadas y mantener la compatibilidad con versiones anteriores tiene un costo para los proveedores de API, y Salesforce no está exento de esto. Por lo tanto, hemos iniciado una hoja de ruta para el retiro de API heredadas. Esto nos ayuda a enfocar nuestros esfuerzos de desarrollo en agregar mejoras con cada nueva versión de API, para que podamos ofrecer innovación mientras mantenemos la confianza. Dato curioso: de hecho, retiramos un pequeño conjunto de API SOAP antiguas en 2018.

Con cada versión principal, las API de la plataforma Salesforce se actualizan automáticamente a una nueva versión y están respaldadas por una política documentada de tres años después de la puesta en marcha. En el lanzamiento de Summer '21, alcanzamos el primer hito de nuestro último esfuerzo de retiro de API heredado. A partir de esta versión, todas las llamadas a la API de SOAP, REST y Bulk con versiones anteriores a la v21.0 siguen funcionando, pero se consideran obsoletas y ya no son compatibles .

Nota: En el contexto de esta publicación, utilizamos el término "API REST" para designar todas las API con URI de punto final en /services/data/vXX.Y/ donde XX.Y es la versión de API. Esto incluye la API REST de la plataforma Lightning "estándar" para trabajar con sObjects y registros, pero también los siguientes recursos:

Para el hito de Summer '22, observe los resultados de una solicitud REST a GET /services/data/v20.0 para comprender el conjunto de recursos de nivel superior que se verán afectados cuando se retiren los extremos v20.0.

Continuaremos implementando nuestro plan de retiro de API en futuras versiones. Estos son los próximos hitos clave (las fechas están sujetas a cambios):

En verano del 22:
- Todas las API principales de SOAP, REST y Bulk con versiones que van desde la v7.0 a la v20.0 se retirarán formalmente y dejarán de funcionar;
- El soporte terminará para las API con versiones que van desde la v21.0 a la v30.0
- Anunciaremos nuestro próximo conjunto de versiones programadas para el retiro
En Summer '23, las API principales con versiones que van desde la v21.0 a la v30.0 se retirarán formalmente y dejarán de funcionar.

Ahora que sabe lo que hemos planeado, hablemos de cómo puede determinar si se ve afectado.

Identificar el uso de API heredado

Para ver si está utilizando API heredadas, puede crear una lista de todas las integraciones que usa su empresa preguntando, pero eso sería largo y propenso a errores. Por ejemplo, tendría que identificar clientes antiguos instalados localmente en las máquinas de los usuarios, como versiones antiguas de Data Loader o integraciones heredadas como Salesforce Office Toolkit no compatible. Afortunadamente, existen herramientas que le ayudarán a analizar el consumo de API de forma automatizada.

Todas las transacciones de la API de Salesforce se registran en los registros de Monitoreo de eventos. El monitoreo de eventos normalmente requiere una licencia específica, pero hemos expuesto el evento de uso total de API ( ApiTotalUsage ) a todos los clientes de forma gratuita, para que pueda monitorear el consumo de API heredado e identificar clientes e integraciones que deben actualizarse.

Veamos cómo puede utilizar este evento para detectar llamadas API heredadas en su organización. El proceso completo está documentado en un artículo de conocimiento , pero hemos creado una pequeña herramienta de utilidad Apex que automatiza esta tarea.

Automatice los cheques con una utilidad

Dirígete a este repositorio y sigue las instrucciones de configuración. El código Apex del proyecto escanea los ApiTotalUsage eventos de ApiTotalUsage e informa las llamadas a las API heredadas que se realizaron durante la ventana de retención de registros.

Las organizaciones habilitadas para API tienen acceso gratuito a los archivos de registro de eventos de uso total de API con retención de datos de un día. Por un costo adicional, puede acceder a este y a todos los demás tipos de archivos de registro con una retención de datos de 30 días.

Si el escáner encuentra llamadas API heredadas en los registros de su organización, verá este tipo de resultado:

Se encontraron versiones de API heredadas en los registros: {SOAP v7, REST v20, BULK_AP v21}

Si ese es el caso, continúe con sus investigaciones manualmente (consulte la siguiente sección de esta publicación). De lo contrario, verá este mensaje:

No se encontró ninguna entrada EventLogFile de tipo ApiTotalUsage.
Esto indica que no se invocó ninguna API heredada durante la ventana de retención de registros.

Esto significa que aún podría haber algunas llamadas API heredadas realizadas en su organización, pero están fuera de la ventana de retención de registros, por lo que no podemos rastrearlas.

Realizar investigaciones manuales

Si necesita impulsar sus investigaciones aún más, este artículo de conocimientos describe bastante bien el proceso. En resumen, tendrá que ejecutar una consulta SOQL para recuperar los ID de los ApiTotalUsage eventos de ApiTotalUsage. Luego, para cada registro de registro, deberá utilizar un cliente HTTP como Postman para llamar a la API REST con el ID de registro para recuperar el archivo de registro asociado en formato CSV.

Como referencia, un ApiTotalUsage eventos de ApiTotalUsage se ve así:

El registro contiene campos clave que guiarán sus investigaciones:

El CLIENT_NAME es especialmente útil para identificar aplicaciones e integraciones que realizan llamadas a API que requieren investigación y ajustes. Siempre es una buena práctica hacer uso del encabezado de solicitud Sforce-Call-Options con un nombre de cliente al realizar llamadas a la API. Esto le ayuda a identificar las llamadas de su cliente cuando mira los registros, y le ahorra tiempo al gobierno de la integración.

USER_ID y CLIENT_IP son útiles para identificar el origen de las llamadas API heredadas, pero existe la posibilidad de que estos valores se compartan entre varias aplicaciones en caso de que se realice un usuario técnico / cuenta del sistema (ID de usuario compartido) o se realicen llamadas desde una ubicación física de la oficina ( dirección IP compartida).

Finalmente, los API_FAMILY , API_VERSION , API_RESOURCE y HTTP_METHOD brindan pistas valiosas sobre el tipo de operaciones que realiza el cliente API.

Actualizar integraciones mediante API heredadas

El procedimiento de actualización dependerá del tipo de API que esté utilizando, pero aquí hay una breve descripción general de lo que se requiere:

Para llamadas a API basadas en SOAP, genere un nuevo WSDL e incorpórelo a la integración afectada
Para los puntos finales REST, actualice el número de versión en el URI a la versión principal actual
Aunque puede actualizar de manera similar los URI para /async en el caso de Bulk API, la forma más gratificante de actualizar las llamadas heredadas es adoptar Bulk API 2.0 y disfrutar de un flujo de trabajo más simple y límites mejorados.

Tenga en cuenta que las aplicaciones pueden realizar llamadas API heredadas utilizando bibliotecas o complementos obsoletos, como la antigua interfaz COM de SForceOfficeToolkit Estas bibliotecas actúan como intermediarias entre las aplicaciones cliente y la API, manejando ciertas tareas implícitamente para que las integraciones sean más simples de codificar. El resultado de aprovechar dicha ayuda es que se pueden enmascarar las definiciones de punto final que incluyen la versión en el URI. Por lo tanto, asegúrese de profundizar en el código fuente si una aplicación afectada está haciendo uso de dicha interfaz. Esta diligencia debida es especialmente necesaria cuando no escribió el código para la aplicación que usted o sus equipos poseen.

Sus usuarios pueden estar usando aplicaciones de escritorio, como Data Loader o Conectores para productos de Microsoft Office, para interactuar con Salesforce. Estas aplicaciones llaman a las API de la plataforma para realizar acciones. Y al igual que las API, Data Loader se versiona con cada versión principal. Por lo tanto, si usted o sus partes interesadas están utilizando versiones antiguas de Data Loader, puede apostar que están llamando a versiones antiguas de las API.

Con todo esto en mente, asegúrese de trabajar con sus administradores para actualizar a los paquetes más recientes para las soluciones de AppExchange instaladas en sus organizaciones. La comunidad de ISV ha recibido alertas de socios con respecto a estos programas de jubilación y está tomando medidas para ajustar sus aplicaciones según sea necesario.

Y recuerde: no importa el cambio, asegúrese de realizar pruebas de regresión para asegurarse de que todo funcione como se esperaba.

Plan para el futuro

Nuestra política documentada para el soporte de la versión API es de tres años. Estaremos pulsando retiros de versiones en futuros lanzamientos de verano con regularidad. Adquiera el hábito de las pruebas de regresión de sus integraciones con cada versión principal tal cual con la versión actual de la API y con una actualización a la última versión. ¡Esto es parte de las mejores prácticas de CI / CD y garantizará que las futuras retiradas de versiones no sean operativas!

En Summer '21, presentamos un encabezado de advertencia en respuesta a las solicitudes de API REST que se realizan en versiones de API obsoletas. La verificación de este encabezado lo ayuda a identificar las llamadas API heredadas automáticamente y lo ayudará a alertarlo sobre otros problemas potenciales con las solicitudes REST en el futuro.

Para obtener más información, consulte el artículo de conocimientos sobre Retiro de las versiones 7.0 a 20.0 de la API de la plataforma Salesforce y el aviso de actualización de la versión "Retiro de las versiones 7.0 a 20.0 de la API de la plataforma Salesforce" (en Configuración, en el cuadro Búsqueda rápida, ingrese "Actualizaciones de la versión"). Para obtener más información sobre el evento ApiTotalUsage para EventLogFile , consulte las notas de la versión de Summer '21 .

Por último, pero no menos importante, hable con los ejecutivos de cuentas y los equipos de éxito del cliente sobre estas retiradas de versiones y cómo hacer un mejor uso de las últimas y mejores versiones de API que se incluyen en todas las versiones importantes. Cada versión trae nuevos sObjects a los que acceder, campos adicionales en sObjects existentes y otras mejoras, incluido el rendimiento y la seguridad.

Sobre los autores

Kris Harrison es directora de gestión de productos en Salesforce dentro del área de servicios de plataforma. Sus equipos de productos se centran en muchos aspectos de la experiencia de la API de Salesforce, incluidas las API principales de SOAP, Bulk y REST, API SDLC e integraciones de API a través de servicios externos. Síguelo en Twitter @GETkharrison o revisa sus proyectos de GitHub muy básicos en @krissirk .

Philippe Ozil es un promotor principal de desarrolladores en Salesforce, donde se centra en la plataforma Salesforce. Escribe contenido técnico y habla con frecuencia en conferencias. Es un desarrollador de pila completa y disfruta trabajar en proyectos de DevOps, robótica y realidad virtual. Síguelo en Twitter @PhilippeOzil o revisa sus proyectos de GitHub @pozil .