REST Queries Reference

This page covers the advanced configuration options for RESTQuery. For the fundamentals --- params, result, defining queries, and the query class rules --- see the Queries guide.

Override Methods

Every static field on RESTQuery has a corresponding get*() method for dynamic logic. When both a static field and a get* method are defined, the method takes priority.

class GetUserPosts extends RESTQuery {
  params = {
    userId: t.number,
    status: t.optional(t.string),
  };

  path = `/users/${this.params.userId}/posts`;

  result = {
    posts: t.array(t.object({ title: t.string, body: t.string })),
  };

  getSearchParams() {
    const status = this.params.status;
    return status ? { status } : undefined;
  }
}

Method reference

Identity Keys

Each query instance is identified by a identity key, which determines its cache identity. Two query instances with the same identity key share the same cache entry and are deduplicated --- only one network request is made at a time.

By default, RESTQuery computes the key as:

${method}:${interpolatedPath}

For example, GetUser with { id: 42 } produces the key GET:/users/42.

Custom identity keys

Override getIdentityKey() when the default key doesn't capture all the inputs that make a query unique:

class SearchUsers extends RESTQuery {
  params = {
    query: t.string,
    filters: t.optional(t.object({ role: t.string })),
  };

  path = '/users/search';

  result = {
    users: t.array(t.object({ name: t.string, email: t.string })),
    total: t.number,
  };

  getIdentityKey() {
    return `search:${this.params.query}:${this.params.filters?.role ?? 'all'}`;
  }
}

This is useful when search params or body fields affect the response but don't appear in the path.

Dynamic Config with getConfig()

For runtime-dependent configuration, override getConfig(). This is useful when caching, network behavior, or retry logic should vary based on the query's params or other runtime state:

class GetDashboard extends RESTQuery {
  path = '/dashboard';

  result = { stats: t.object({ visits: t.number }) };

  getConfig() {
    return {
      staleTime: 60_000,
      gcTime: 30,
      networkMode: NetworkMode.OfflineFirst,
    };
  }
}

When both a static config field and getConfig() are defined, the method takes priority. See the Caching & Refetching guide for details on staleTime and gcTime, the Offline & Persistence guide for network modes, and the Error Handling guide for retry configuration.