API calls
| Synchronization |
|---|
An application programming interface (API) is a communication protocol or interface between client and server computers. When a client device requests data from the server, this is called an API call.
In our environment, Resco uses API calls to request data from the CRM server. Growing number of CRM server providers restrict the number of API calls per time period, or have pricing related to this number. Therefore, it becomes increasingly important to understand how and when Resco mobile apps talk to the CRM server. Fortunately, careful setup of your app project can help you optimize the number of API calls.
Functions that consume most API calls
There are two main areas that consume API calls:
- Synchronization
- Online mode
During synchronization, the consumption of API calls can differ largely based on the following aspects
- Number of entities / objects enabled in Woodford. For Salesforce, even field count may matter.
- Sync Filters on entities / objects
- Enabled Resco features (e.g., attachments, Sync Analyzer, Multi-Layout support)
- Frequency of synchronization
In online mode, Resco mobile apps act like a remote terminal to the CRM server. Displayed data must be downloaded from the server and any change is immediately applied to the server – all of this is realized using API calls. API call consumption depends mainly on:
- The amount of displayed information. Images, associated lists etc. – they all cost extra API calls.
- The way this information is presented. For example opening tabs on demand (i.e. avoiding use of New UI) can save a lot of API calls.
- Additional API calls may come from auditing – if this feature is activated.
There are other features that contribute to API calls consumption in both online/offline modes:
- Location tracking may produce up to 1 API call / min when the tracked device is moving. (During the tracking period, of course.)
- Chatter consumes 1 API call per message. (Windows Desktop platform does not have a notification mechanism and therefore we run a server query every minute.)
Dynamics limits (March 2019)
The following limits apply to Dynamics 365 for Customer Engagement (later called Dynamics) as of March 2019:
- Max 4000 requests per sliding 300 seconds window.
- Combined execution time of incoming requests cannot exceed 1200 seconds over a time window of 300 seconds.
If the limit is exceeded, server returns HTTP error 429 (Too Many Requests), and the internal SOAP fault reports one of the following error:
- Error -2147015902: Number of requests exceeded the limit of 4000, measured over time window of 300 seconds.
- Error -2147015903: Combined execution time of incoming requests exceeded limit of 1,200,000 milliseconds over time window of 300 seconds. Decrease number of concurrent requests or reduce the duration of requests and try again later.
- Error -2147015898: Number of concurrent requests exceeded the limit of X
Note: Existing versions of Resco mobile apps display these error texts to the user.
Dynamics limits (October 2019)
The limits depend on your license:
| User license | # API requests / 24 hr |
|---|---|
| D365 Enterprise apps | 20,000 |
| D365 Professional | 10,000 |
| D365 Team Member | 5,000 |
| etc. (more plans exist) |
From the perspective of Resco mobile apps, practically all server calls count:
- All CRUD operations (create, read, update, delete), share, assign.
- From any client/app, using SOAP/REST endpoints.
Important:
- Implied API calls issued by server plugins, (async) workflows etc. are counted, too.
Exceeding request capacity
What happens if any user exceeds the licensed request capacity? The current policy is that end users are not blocked from using the app for occasional and reasonable over-consumption. Server admins are notified and can react as needed.
See Microsoft documentation for details.
Azure throttling
Microsoft Azure is throttling Resource Manager requests. These limits are usually less important. They apply to Dynamics hosted on Azure, but also to Resco Cloud hosted on Azure.
For each Azure tenant, Azure Resource Manager allows up to 12,000 read requests/hour and 1,200 write requests/hour. These limits are scoped to the security principal (user or app) making the requests and the subscription ID or tenant ID. If your requests come from more than one security principal, your limits increase.
Real limits are usually much higher, also because they apply to one ARM instance, while there are usually multiple ARM instances in your region.
If the limit is exceeded, server returns HTTP error 429 (Too Many Requests).
Estimating API calls
The following formulas can give you an estimate of API calls made during the synchronization and online mode. Only the communication with Dynamics CRM server is counted. Calls to SharePoint/Exchange, etc., are not subject of any limit.
If you're using Salesforce CRM, you can find similar analysis below.
Full synchronization
Add the following numbers together to receive a rough estimate of API calls needed to perform a full synchronization in your project. Round up.
- ~15 for preparation phase (without new customization)
- number of entities / 2
- number of records / fetch_page_size (Max 5000, Default = 500)
- number of NN records / 2000
- number of ActivityParty records / 2000
- number of attachments
- number of images
- 1 (if audit is used)
Incremental synchronization
Add the following numbers together to receive a rough estimate of API calls needed to perform an incremental synchronization in your project. Round up.
- ~11 for preparation phase (Same as for FullSync except permissions are loaded only at 1st sync after AppStart)
- 1 (DeletePlugin)
- number of changed entities (for uploader; see also comment below)
- number of entities * 1.2 (SyncAnalyzer + downloader)
- number of NN entities
Note for uploader: This maybe sound like a low number, but it is usually correct. However, there are some cases when uploader is quite costly:
- If you have many local changes (default batchsize=100) - this is typically the case for Inspections
- Every upload problem costs extra API calls (upload retries, conflict resolution...)
- Status changes cost extra API calls
Online mode
Every single action performed in online mode consumes API calls: whether you open a list or a form, display an image, save your changes, etc.
Views
- Open: 2 calls
- Browse: 2 calls / page (~50 items)
Forms
- Load: 2-50+ calls/form
- Save: 1 or more calls
Audit actions (depending on your project) consume additional API calls, and so does business logic written in JavaScript extensions.
Any serious work in online mode will sooner or later consume more API calls than synchronization. This is valid even for full synchronization of huge app projects. Why? Lot of actions generate several API calls. Extreme example: opening of a single complex form with several related / unrelated lists in online mode can take dozens API calls.
Recommendations
Install Resco Mobile CRM app version 12.2.2 or later. The sync log contains API call statistics in the following format:
<ApiCalls Prepare='...' Uploader='...' SyncAnalyzer='...' Downloader='...' Images='...' Total='1234' />
The value listed in Total attribute represents the total number of API calls made during the synchronization.
Notes:
- Salesforce / Resco Cloud numbers are not reliable at this point. We are planning to correct this in v12.3 release.
- API calls issued by Resco mobile apps may induce additional API calls made by server plugins. (This mainly concerns sync uploader or save operation in online mode.)
- Resco mobile apps cannot monitor these extra calls, but you should take them into consideration when making API calls estimates.
Below are some maxims how to minimize API calls number.
- Online mode
- Do not use New UI (Then the tabs are loaded on demand.)
- Synchronization
- Use large fetch page size (Advanced sync setup):
- By default 500 records = 1 API call.
- Using page size 5000 (maximum) decreases the number of API calls to one tenth. However, larger page size may result in lower app responsiveness and requires more memory.
- Decrease number of downloaded attachments (1 attachment = 1 API call)
- Minimize data downloaded by the client (using Sync Filter)
- Avoid useless downloads:
- All records that are deleted in the FullSync cleanup need not be downloaded at all.
- SyncAnalyzer:
- Dynamics / Resco Cloud: If you are sure you don't need this module, switch it off. You might save about numEntities/10 API calls during IncSync.
- Salesforce: SyncAnalyzer saves a lot of API calls during IncSync. (Due to batching several requests into one API call.)
- Automatic synchronization
- Do not overuse. Normal IncSync takes ~50-100 API calls.
Salesforce
Sync download
- Initialization - 4 calls
- Metadata and permission synchronization – 1 call + 1 call per 200 objects enabled in the app. Only on first sync after app is started.
- Check server deletes – 1 call per 25 objects enabled in the app. Many server deletes increase this number. Only applies to incremental synchronization.
- Download layouts – 1 call + 1 call per layoutable object enabled in app. Only on first sync after app is started. Can be disabled in Woodford configuration (Disable Multiple Layouts Support). Warning: disabling multi-layout also disables Picklist per record-type feature!
- Sync Analyzer – since Resco version 12.0, it consumes 1 call per 25 objects enabled in the app. This applies to incremental sync only. It checks how many records have changed since last synchronization for each object. It saves one API call per object with no changed record. It is also especially useful if many records falling outside of defined Sync Filter are often changed on server. Since version 12.0, in order to save API calls, it is recommended to always have it enabled.
- Download records
- Full sync – for every object enabled in the app, 1 call per returned result page. Page size is determined by Salesforce, normally it is 1000-2000 records, but can be much less – especially if you enable many fields in Woodford.
- Applying good sync filters can significantly save API calls (and time the full sync consumes).
- Incremental sync with Sync Analyzer – only for objects where Sync Analyzer detected changes. This means 1 call per page of changed records. If Sync Analyzer detected too many changes, full sync for the object is performed instead.
- Incremental sync without Sync Analyzer – for all objects enabled in Woodford, 1 call per page of changed records.
- Attachment download – 1 call per attachment/file/document with binary content.
Sync upload
- Created/Deleted/Updated records – 1 call per 200 objects on average – assuming you are using the newer Collections API, rather than the legacy Batch API. (You can control this behavior in project configuration, Force legacy batch upload API.)
- Retry on failed records – 1 or 2 calls per object.
Recommendations
- If possible, avoid using Online Mode. When you absolutely need to use Online mode, consider disabling "Flexible Forms" in Woodford ("New Form UI" option in the app), because the new UI loads automatically all sections, while the old interface loads only the active tabs.
- Starting from version 12.0, enable Sync Analyzer.
- Up to version 11.3, disable Multi-layout support.
- Use Salesforce visibility and sharing options to limit number of records users can see.
- Set up Sync Filters to limit number of downloaded records, especially binary attachments, files, or documents.
- Only enable objects and fields you really need in the app.
- Set up synchronization policy with your user to minimize number of synchronizations. For example, automatic background sync on every change can lead to extensive API consumption.
- Since version 12.2.2 you can inspect API consumption in the ApiCalls section of Sync Log (e.g. using Sync Analyzer). The value listed in "Total" attribute represents the total number of API calls made during the synchronization. (Subtract XrmServer calls as these involve Resco Cloud calls, not Salesforce.)
<ApiCalls Prepare='9' Layouts=’10’ Uploader='11' DelPlugin=’12’ SyncAnalyzer="13" Downloader='14' XrmServer=’15’ Attachments=’16’ Total='100' />.