Vista API Concepts

There are several concepts unique to the Vista API for identifying changes in the Vista database, manipulating data, and making API calls.

API Connection to Vista

The Vista API does not directly connect to or interact with your Vista instance, rather, API calls go to the App Xchange cache, which stores a copy of your Vista data.

In order for the App Xchange cache to access your Vista data, the Xchange Agent must be installed. The Xchange Agent is a Windows service that is installed on the same server as your Vista database. It securely provides access to your Vista database and copies your data into the App Xchange cache. During the hourly scheduled cache writes, the Xchange Agent searches for any differences between the Vista database and the data in the App Xchange cache, updating the cache to match.

When you make an API GET call, the data in the API response comes from the Vista data stored in the App Xchange cache (that is typically refreshed on an hourly interval).

App Xchange Cache

The App Xchange cache exists as a midpoint between the Vista database and the API call. When you make an API call, the data is returning from the App Xchange cache, not your Vista instance.

The Xchange Agent is what discovers new, updated, and deleted Vista records on a scheduled basis (typically every hour). Outside of the hourly cache write, actions also update the cache for new or updated records when the action result shows successful.

The Vista API is asynchronous, requiring scheduled cache refreshes.

Move Data In and Out of Vista

The Vista API has two primary behaviors for moving data in and out of Vista: action processing and cache writing. These behaviors identify changes in the Vista database and manipulate data as needed.

Action Processing

When an action (such as creating, updating, or deleting data) comes into the App Xchange platform, it is queued and processed before going to the Vista database. The Vista database responds with the results of the action (such as updating a Vista table with new data). The App Xchange cache record updates with the results of the action as well.
Actions are presented as POST endpoints and are used to modify data.

Read more about the nuances of action processing in the section below on Action Processing Responses.

Cache Writing

The caching behavior looks for changes in the Vista database and replicates those changes in the App Xchange cache, so that they are available to the Vista API. When you make an API call, the data is returning from the App Xchange cache, not your Vista instance.

Data in the cache is presented as GET endpoints. Caching is used to read data.

The section above on the App Xchange Cache describes the cache in more detail.

Throttling / Rate Limiting

The Vista API does not have throttling or rate limiting.

Custom Field Handling

You can make API calls to manipulate data in custom fields on all standard Vista tables. However, you cannot make calls to data in custom tables. The hourly cache write automatically picks up changes to custom fields.

When making an API call, you must use the following formatting:

• Custom fields must be an object.
• Line item types must be an array.

Understanding Vista API Endpoints

There are multiple different endpoints you can use to access each Vista record and interact with the data.

For example, both of the following endpoints get an invoice batch entry object from the cache, but use different paths and parameters to access this data:

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/keyid/{KeyID}

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/natural/{Co}/{Mth}/{BatchId}/{BatchSeq}

Both of the following endpoints get an invoice batch entry object for the provided {ryvitId_value}, but use different paths to access this data:

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/keyid/{ryvitId_value}

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/__ryvitId/{ryvitId_value}

NOTE: Support recommends that you use the Vista indexes of keyid or natural. These allow you to interact with the cache using the same keys that Vista uses (as opposed to using the __ryvitId index).

Endpoint Filtering Clarity

Consider the specific GET or POST request you want to use based on your purposes or what functionality you're trying to build into an integration.

For example, instead of getting all invoice batch entry objects from the cache, which you would use this endpoint to retrieve:

 /subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache

Instead target the specific object(s) you want with a more specific GET request, such as this, which uses the KeyID to identify a particular record:

 subscribers/{subscriber_code}/vista/ap/2/data/inv_batch_entries/cache/keyid/{KeyID}

Action Processing Responses

Using a POST request sends an action (such as creating, updating, or deleting data) to the App Xchange platform, where it is queued and processed before going to the Vista database. The initial response includes the following: id, operation (whichever endpoint you called), and status (queued).

Wait for the action to process (this takes about 30–40 seconds), then use this id and call the API again to get the completed response and additional details.