We’re working with a client to support an integration with a commercial application. I have recommended we create a custom web service supported by salesforce, but they asked a reasonable question: “Why couldn’t we use the Salesforce API directly instead of having someone build the web service?”
Here’s why I recommend the custom web service approach when dealing with a critical Salesforce integration. First you can absolutely use the standard REST API, and nothing stops you from doing this today. Just note, if the REST API is being used, the connected app needs to be created regardless of approach.
I recommend the custom service approach, especially when product development teams are involved, for the following reasons:
Prevent tightly coupling databases
- When the standard API is used, the API queries and writes to each object and field as if you’re querying and writing to the database directly. This tightly couples the two applications, meaning a change to Salesforce can and will cause the integration to fail. See below for the fact that these failures will not be logged or allow for an alerting mechanism. Updates to the parent campaign structure will then require the product development team to be engaged to accommodate these changes.
- A custom service built on the API will prevent this coupling of the systems because you don’t need to know anything about the Salesforce data model, field names, etc. you’ll get a json file that is abstracted from the Salesforce data model. This makes developing the services on your side much easier.
- Along with the below testing, monitoring and alerting functions, this is the only way to ensures changes to Salesforce will not break the integration.
We can provide a nested response in a query:
- A custom service is the only way we can provided nested information in the json response, for example an account ID will be given and we’ll return the account info and nest a repeating set of child information into this single json file.
- The standard API requires a call per object with the destination responsible for re-assembling object relationships. This means you need to call 1. the account 2. the child record and 3. the child’s related data. You then need to process all this data to re-assemble it into a usable way, I feel a single json file with this data nested is much easier to work with.
Error handling for database update calls
- The standard API does not naturally log errors as they’re returned in the API response. This means service requests are not logged anywhere in Salesforce, making error reporting in Salesforce impossible.
- This means 100% of error handling must be done by the external application. You will get errors like record update fails, missing ID’s, validation rules, additional automation failures which roll back the entire transaction, etc. To prevent you from creating routines for all these error types, I argue to receive the json file by a service handler. This way the class can manage the database errors in Salesforce, and if an error can’t be reconciled, the data can be stored in a log file and alerted / reported.
- This decouples the two applications, and means the application doesn’t need to worry about issues that would cause a database write / update to fail, without this the dev team will be responsible for creating a fairly robust error handling application in the destination application.
Web service monitoring
- In Salesforce it’s difficult to test if the standard API will receive an api call successfully and return an expected query or allow a database update. This is not the case for a custom web service where a test method can be created to test the operation of the service on-demand. This test can then be scripted to create an alerting function if the service will not successfully return data or allow the update to the campaign record.
The custom service is built on the API:
- These services are essentially built on the Salesforce API. Salesforce gives the ability to create these custom classes to address the points above, not re-creating the API.