1. API
  2. XML API and SOAP API
  3. API Best Practice Guidelines
  4. Optimize the API Integration

Optimize the API Integration

The following suggestions will help you get the most out of your API integration. Discuss them with your OpenAir Professional Services consultant to ensure you understand why they improve the efficiency and effectiveness of your integration.

Make Batch Calls

When making calls in your API integration, request and update data records in batches. Typically, you should group records into batches of 500, but the specifics vary depending on the context and the expected volume of data to be transacted. Even when requesting data based on filtering criteria, multiple read operations can be specified within one read request. You should run batch operations during off-peak hours to minimize impact on integration performance.

Make Fewer Calls

Reducing the number of calls you make to the API improves the performance of your integration. Because API calls require a call and response over the public Internet, they can consume both time and resources. Minimizing the number of calls you make increases the speed at which your API integration operates. Running batch operations during off-peak hours also minimizes impact on performance.

You should read and update custom fields inline with standard object properties instead of using the legacy custom equal to method. If you work with the SOAP API, use the account-specific WSDL, which includes custom fields. If you work with the XML API, set the enable_custom attribute to 1. For more information about working with custom fields, see Custom Fields.

You should not run the API from multiple clients simultaneously. Concurrent connections are technically possible but they may cause performance deterioration due to contention on Web and database servers' resources and can affect the performance of both the API integration and user interaction.

Note:

Throttling controls apply to API usage. Batching multiple API operations into one request and caching data locally are the best methods to avoid our servers ever triggering throttling controls.

For information about throttling controls, see API Limits.

Cache Locally

Transactional records in OpenAir contain as many as a dozen foreign keys that refer to other records in the system. When retrieving a batch of transactional records, you will often be retrieving many records with the same foreign key value. You could retrieve many charges for the same project (with the same projectid) or many time entries for the same user (with the same userid), for example.

To optimize performance, after retrieving a batch of charges, you should construct a message to retrieve all the project records associated with those charges and hold those project records locally, either in memory or using persistent storage, to use with the next batch. To ensure the persistent cache is up to date, the client application can retrieve data using a newer-than filter. You should retrieve list data, cache it, and then keep it in synchronization with OpenAir by retrieving records that have been modified since the previous update. The XML API and SOAP API lets you read records that have been deleted since the last request, which is another way to ensure your local list data cache is up-to-date.

Another way of optimizing performance is paying attention to the range of possible foreign key values for an attribute. This range of values could be small. Even a large OpenAir account may have only 3 or 4 time types, for example, and every time entry record will then have one of those 3 or 4 values. After you retrieve the time type records, you can hold them locally for an indefinite period as time type values change infrequently and the same small set can be referenced on every time entry transaction.

Use External IDs

In addition to caching locally, you can use an external ID [externalid] saved in OpenAir in place of an OpenAir internal ID when related data is being referenced on a OpenAir record during a modify or add operation. This often avoids the need to request the OpenAir list data in the first place. The integration logic should properly manage possible errors if the externalid was not found in OpenAir system. See Update Using External ID as Foreign Key Lookup — C# and Modify with Foreign Key Lookup — Java.

Use Date Filters to Limit Amount of Data Processed

Make sure you are only requesting data that is new, modified, or deleted. When requesting list elements like projects, as mentioned previously, you should keep a local cache of records. See Cache Locally. Issuing a read method call that requests records that have been added, modified or deleted since the previous integration run allows the integration logic to process only a small data set of changed records. By default, the newer-than filter uses the updated date on each record, which is the timestamp appropriate for such use. For code examples, see Read Not Exported Expense Reports with all Method and Date Filter — C# and Read with all Method and Date Filters — Java.

Use not-exported Filters to Limit Amount of Data Processed

Make sure you are only requesting data that has not previously been exported. For transactional exports, you should export approved entries and mark these records in the OpenAir system as having been exported. You can configure OpenAir to lock exported data so that it cannot be modified after the export. You can also configure OpenAir reports and lists to show records as having been exported to another system. Export child elements and mark these child elements as being exported. For example:

  • Use the not-exported filter when you export invoices [Invoice] and their charges [Slip]. Since charges are the child elements of an invoice, you can mark each charge as exported. Subsequent integration runs issue a read request and the not-exported filter only returns qualifying transactions, that is transactions not previously processed.

  • Use the not-exported filter to export Task records for timesheet information.

  • Use the not-exported filter to export Ticket records for export expense information.

For code examples, see Read Not Exported Charges with all Method — C# and Read Not Exported Charges with all Method — Java.