You can call Api.Get<T>() to invoke a GET based API. The parameters can either be embedded in the url (route) or added as query string. 

await Api.Get<Order[]>("api/v1/orders");

// Or with query string parameter:
await Api.Get<Order[]>("api/v1/orders?from=" + fromDate);

// You can also use an anonymous object for sending query string parameters:
await Api.Get<Order[]>("api/v1/orders", new { from = fromDate, to = toDate, ... });

Caching Get call results

Whenever the server returns a valid response (which is often Json) it will be saved in the application as a local file under  Resources\-ApiCache\[URL-HASH].txt which can then be used in the future when the same URL (i.e. the same API with the same parameters) is called when the network or server is unavailable or there is any error. This allows the application to function in a read-only mode when offline.

Note: In certain scenarios you should delete the cache. For example when logging out, it's very important to delete the cache folder to prevent previous user's data being accidentally revealed to a new user account, and to prevent errors. You can achieve that using the following:

await Api.DisposeCache();

ApiResponseCache parameter

An optional parameter of Api.Get() is called cacheChoice which you can set to any of the following:

• Prefer: Means if a cache is available, that's preferred and there is no need for a fresh Web Api request.
• PreferThenUpdate:  If a cache is available, that's returned immediately. But a call will still be made to the server to check for an update, in which case a provided refresher delegate will be invoked.
• Accept (default): Means a new request should be sent. But if it failed and a cache is available, then that's accepted.
• AcceptButWarn: Means a new request should be sent. But if it failed and a cache is available, then that's accepted. However, a warning toast will be displayed to the user in that case to say: The latest data cannot be received from the server right now.
• Refuse: Means only a fresh response from the server is acceptable, and any cache should be ignored.

OnError parameter

Another optional parameter of Api.Get() is called errorAction, which allows you to specify what should happen in case the network or server is down, or there is any problem in processing the response. For example:

await Api.Get<Order[]>("api/v1/orders",  OnError.Ignore);

The default option is to show a Toast.  Learn more about OnError.

Example configurations

If the API responds successfully with no error, the fresh result will always be returned and your extra parameters will be ignored anyway (unless Cache option of Prefer is used). But if an error occurred, then use one of the following options depending on what outcome is acceptable for you:

• A: Accept the latest cache. If none is available, inform the user to prevent confusion and return null (don't throw):
  return await Api.Get<Order[]>("...");
  // which means the default parameters of:
  return await Api.Get<Order[]>("...", OnError.Toast, ApiResponseCache.Accept);
• B: Don't accept the cache. Inform the user and return null (don't throw):
  return await Api.Get<Order[]>("...", OnError.Toast, ApiResponseCache.Refuse)
• C: Don't accept the cache. Just throw. 
  return await Api.Get<Order[]>("...", OnError.Throw, ApiResponseCache.Refuse)
• D: Accept the latest cache. If none is available, throw:
  return await Api.Get<Order[]>("...", OnError.Throw, ApiResponseCache.Accept)
• E: Accept the latest cache. If none is available just return null without informing the user:
  return await Api.Get<Order[]>("...", OnError.Ignore)
• F: If we already have it cached, just use that (fastest option) and don't even send a new request.
  return await Api.Get<Order[]>("...", ApiResponseCache.Prefer);
• ...

Where to use it?

It's recommended to make all API calls in your business domain or service classes in the App, which will be then called in your UI.

Example:

public class Order
{
     ...
     public static Task<Order[]> GetOrders() => Api.HttpGet<Order[]>("v1/orders");
     ...
}This simple line is enough to handle all things related to invoking an API including: deserializing the result, handling exceptions, using the latest cache if the network or API server is down, informing the user, ...

In the UI then you can use this as your list module's data source.

<ListView ... DataSource="@await Order.GetOrders()" />

Best practice for fastest UX -> ApiResponseCache.PreferThenUpdate

Imagine a page which uses GET APIs to fetch and show a list of some data. At the first time that you visit that page, fresh data will be downloaded, cached locally and rendered.

In a typical scenario, you will probably go to another page and then back to this page. When you go back, the remote data may or may not have been changed. And you don't know what's the case. So you have to call the Web API for fresh data and wait for the response before rendering the page which will slow things down and annoy the user.

Zebble provides a better way!

• When calling Api.Get(...) you can select the PreferThenUpdate cache option which makes the framework to immediately return the previously cached data (if available), which makes the page render immediately.
• It will then also, in parallel, send a fresh request to the server to ask for fresh data.
• If and only if the returned data is different from its previous cache (from which the UI is already rendered) then the UI will be refreshed to show the updated data. To achieve that you should provide a delegate which will update your UI.

This way every page of your app will be displayed immediately, providing the best user experience. Then if the data was changed, it will then reload the UI to reflect that, often in less than a second.

Example:

...
<ListView z-of="Product, Row" Id="ProductsList" DataSource="Items">
      .....
</ListView>And in the code behind:

Product[] Items;
bool IsReturnVisitToCachedPage = false;

public override async Task OnInitializing()
{
      Items = await GetOrRefreshDataSource();

      await base.OnInitializing();
      await InitializeComponents();
      ...

    // If the page is cached, every time the user comes back to this page the ShownEvent will be fired (but not OnInitializing).
    // If you specifically don't want the page to be cached, you can remove it.
     await WhenShown(() =>
     {
           if (IsReturnVisitToCachedPage) await GetOrRefreshDataSource();
          else IsReturnVisitToCachedPage = true; // for next time
     });
}

Task<Product[]> GetOrRefreshDataSource()
{
     return Api.Get<Product[]>("api/v1/products", ApiResponseCache.PreferThenUpdate, Refresh);
}Task Refresh(Product[] items) => WhenShown(() => ProductsList.UpdateSource(Items = items));