Response Polling
Updating data from AppFolio® can take time. Our caching helps ensure our API responds quickly when we already have the data. This document outlines best practices when updating data from AppFolio® through Skywalk API.
Updating from AppFolio®#
You can update your data from AppFolio® by configuring an API call to request new data or by setting up Scheduled Jobs to automatically update your data.
Polling Lifecycle#
When Skywalk API grabs new data from AppFolio®, the API will begin updating the data in the background. Meanwhile, your API requests will still return immediately. By default, your API requests will still return the previously stored results. To get the updated data, you will need to poll the API.
See Webhooks if you prefer event-driven architecture.
Response Format While Updating#
When an update begins, the meta.status field in the response will change to updating. This denotes there is an active update happening in the background which means it's safe to begin polling.
Polling is performed by repeating the same request every 5-10 seconds, until the meta.status is no longer updating.
This response also returns the most recent data cache, to ensure your application will consistently retrieve the latest available data. The meta.lastUpdated field denotes when the data returned was retrieved from AppFolio®.
If no data is available from the cache, the data property will not be present in the response, and the meta.lastUpdated will be null.
Response Format When Completed#
When an update completes successfully, the meta.status field in the response will change to ok. This denotes the data in the response is the most up to date.
When successful, the meta.lastUpdated field will update to reflect the new time the data was retrieved from AppFolio®.
Response Format On Error#
When an update completes with an error, the meta.status field in the response will change to stale and the meta.lastUpdated field will remain the same. This denotes the data in the response failed to update due to an application error.
Your applicaiton should stop polling and decide whether to use the stale data (if applicable) and/or retry your request after a few minutes. Please reach out to support if this error continues after retrying your request.
Data Update Details API#
Currently the only way to see past data update requests and data update details is through the Skywalk API dashboard.
Polling Best Practices#
While each implementation may have different requirements, there are some general rules we recommend when implementing polling:
- Wait at least 5-10 seconds before the second poll
- Do not poll more than once per five seconds
- Do not retry a failed update more than once
Following these rules will help limit network strain and improve the performance of your application.
Polling more frequently will not help. Our response cache layer will limit the frequency of updates.
Response Cache Layer#
All responses from our API go through our cache layer.
Our cache layer works as follows:
- A
response.meta.statusofokis cached for 5 minutes. - A
response.meta.statusofstaleis cached for 1 minute. - A
response.meta.statusofupdatingis cached for 5 seconds.
This should be taken into account when designing your polling and request timing.