Redacción de los servicios REST de Apex (y cuándo no hacerlo) ☁️

Apex es el lenguaje central para personalizar la lógica comercial en la plataforma Salesforce y para la integración con sistemas de terceros. Siempre que necesite exponer datos de la plataforma o lógica personalizada a un sistema externo, una de sus opciones es crear un punto final REST de Apex personalizado. En esta publicación, analizaremos los casos de uso para implementar puntos finales REST de Apex personalizados y compartiremos consejos sobre cómo implementarlos y probarlos.

Comprender los casos de uso y las alternativas a los puntos finales REST personalizados

Los puntos finales REST de Apex personalizados son bastante potentes porque le brindan un control total sobre la lógica comercial para su integración. Sin embargo, es fácil pasar por alto el hecho de que su código de terminal personalizado genera un costo de mantenimiento y que hay una serie de alternativas que no requieren código en el lado de Salesforce.

Salesforce tiene un amplio conjunto de API que pueden cubrir sus necesidades de integración:

• La API REST es la API más flexible. Entre otras cosas, expone operaciones CRUD en registros y consultas sobre otras entidades, como objetos de modelo de datos o límites. Sin embargo, las solicitudes a esta API operan fuera de las transacciones, y esto puede ser un problema cuando necesita encadenar operaciones de escritura en el contexto de una integración. Por ejemplo, si necesita actualizar tres registros y la segunda solicitud falla, debe implementar una estrategia de reversión manual para cancelar la primera operación.
• La API compuesta es una gran adición a la API REST. Le permite encadenar llamadas API REST dentro de un contexto transaccional gracias a un indicador allOrNone (ver documentos ). Tenga en cuenta que los cambios se pueden revertir en caso de errores. Además, admite operaciones encadenadas para crear registros vinculados, como una Cuenta, una Oportunidad y un Contacto, con una sola solicitud.
• LaAPI de la interfaz de usuario es excelente para recuperar datos y metadatos asociados con objetos y registros en llamadas de API únicas. También admite operaciones CRUD en registros individuales.
• La API de GraphQL (Beta a partir del lanzamiento de Summer '22) es la última incorporación a la familia de API. Aprovecha el lenguaje de consulta estándar de GraphQL y le permite ejecutar consultas en la API de la interfaz de usuario. A diferencia de otras API, la API de GraphQL es de solo lectura.

Lea la documentación de esas API y explórelas con herramientas como la colección de API de Salesforce Platform para Postman . Luego, si su caso de uso requiere alguna lógica de negocios personalizada, como el cálculo usando varios registros y una serie de operaciones CRUD que las API no pueden cubrir, puede implementar un punto de enlace REST de Apex personalizado.

Exponer un punto final REST personalizado con Apex

Implementar un punto final REST personalizado

Lo primero que debe hacer es crear una clase de Apex global anotada con @RestResource (consulte los documentos ) y una propiedad urlMapping . Esto le permite exponer su recurso usando un patrón de URL como:

Tenga en cuenta el uso de un carácter comodín opcional * en nuestro valor de urlMapping . Esto capturaría todas las siguientes URL de solicitudes HTTP donde MY_DOMAIN_HOST es el nombre de host de Mi dominio:

Importante: a diferencia de Apex, las URL distinguen entre mayúsculas y minúsculas. Como práctica recomendada general de REST, mantenga las URL en minúsculas.

Ahora que ha declarado una clase de recurso REST, debe crear uno o más métodos de Apex para capturar solicitudes de varios métodos HTTP . Para hacerlo, deberá declarar los métodos de Apex estáticos anotados por uno de estos:

Por ejemplo, el siguiente método captura todas las solicitudes GET entrantes para nuestro recurso REST. El nombre del método no tiene importancia, pero se recomienda que al menos mencione el método HTTP para simplificar las pruebas (spoiler: estará llamando al método en sus pruebas).

Si es necesario, puede agregar la anotación @ReadOnly (ver documentos ) a su método. Esto duplica el número máximo de filas devueltas a 100 000 para las consultas SOQL que se ejecutan en este método. Como nota al margen, la anotación @ReadOnly no se limita a los métodos de extremo REST, también está disponible para los servicios web SOAP y la interfaz programable.

Ahora que tiene la firma del método, el siguiente paso es implementar su cuerpo. Para hacerlo, confiamos en la clase System.RestContext (consulte los documentos ) para capturar los detalles de la solicitud entrante como una instancia de System.RestRequest (consulte los documentos ).

Con esto, así es como se vería la implementación de una solicitud GET "Hola, mundo":

En nuestro ejemplo, el método devuelve una cadena, pero puede trabajar con cualquier tipo de objeto o contenido binario. Cada vez que especifica un tipo de devolución para el método de Apex, la Plataforma de Salesforce serializa su valor como JSON en el cuerpo de la respuesta.
Si desea tener más control sobre la respuesta, puede trabajar con un método void y pasar el resultado a una instancia de System.RestResponse (ver docs ) que recupera del RestContext . Esto le permite controlar el tipo de devolución, los encabezados y el código de estado HTTP .

Aquí está el mismo ejemplo de "Hola, mundo" usando RestResponse :

Otra sutileza que vale la pena mencionar es que si su solicitud tiene un cuerpo JSON, puede extraer valores automáticamente gracias a los parámetros del método Apex. Por ejemplo, si el cuerpo de su solicitud usa este formato:

Puede capturar valores de parámetros con esta firma de método de Apex:

Ahora que sabe cómo implementar un punto de enlace REST de Apex personalizado, veamos cómo puede escribir pruebas para él.

Escribir pruebas de Apex para un punto final REST personalizado

Al probar su punto final, simplemente puede falsificar el objeto RestContext para pasar sus valores de prueba. Por ejemplo, esta es una prueba que cubre nuestro ejemplo de "Hola, mundo". Tenga en cuenta cómo falsificamos el URI de solicitud y el método HTTP e invocamos directamente el método que estaría expuesto como un recurso HTTP.

Al probar un método de punto final vacío que usa RestContext.response en lugar de un tipo de retorno, puede verificar la respuesta del servidor desde el contexto de prueba:

palabras de cierre

Esto concluye nuestra publicación sobre puntos de enlace REST de Apex personalizados. Ahora debería tener una buena idea de las alternativas para escribir su propio punto final y, si se trata de esto, cómo puede implementar uno con las pruebas relacionadas. Asegúrese de consultar nuestra aplicación de muestra Recetas de Apex para ver ejemplos de recursos REST de Apex y sus pruebas asociadas. Recuerde siempre que el código que no escribe es código que no tiene que mantener.

Recursos

Recursos de puntos finales de Apex personalizados

Recursos de la API de Salesforce

Sobre el Autor

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