10.3.1 Cache Parameters🔗

When set, the cache is always consulted before making GET requests—if matching cached data exists, it is returned instead of calling the API.

Path resolution: Relative paths are resolved against current-directory at the time of each cache operation. If you change directories during a session, cache lookups will use the new working directory. Use an absolute path if you need consistent behavior regardless of working directory.

Directory creation: When writing to the cache, the directory is created automatically (including parent directories) if it doesn’t exist.

Disk-only: The cache is purely file-based with no in-memory retention. Each cache lookup reads from disk. This means cached data survives program restarts, but there’s no speed benefit from repeated lookups within a session beyond filesystem caching.

;; Relative path (resolved against current-directory)

(current-bc-cache-dir "bc-cache")

;; Absolute path (recommended for consistency)

(current-bc-cache-dir "/path/to/cache")

;; Absolute path based on current location

(current-bc-cache-dir (path->string

(build-path (current-directory) "bc-cache")))

• 'manual (default): Responses are never auto-saved. Use bc-cache-put! to manually populate the cache.

• 'all: Every GET response is automatically saved to the cache.

In both modes, cached data is always used when available. The mode only affects whether new responses are written.

10.3.2 Entity-Based Cache API🔗

The primary cache API works with bc-entity structs, using the current configuration (current-bc-tenant, current-bc-environment, current-bc-company) to construct cache keys automatically.

• (bc-cache-put! entity data) — Cache the list endpoint response

• (bc-cache-put! entity data query) — Cache a filtered list response

• (bc-cache-put! entity id data) — Cache a single record by ID

;; Cache all customers

(bc-cache-put! customers

'#hasheq((value . (#hasheq((id . "abc") (name . "Acme"))

#hasheq((id . "def") (name . "Beta"))))))

;; Cache filtered results

(define active-query (make-query #:filter (= 'status "Active")))

(bc-cache-put! customers active-data active-query)

;; Cache a single customer

(bc-cache-put! customers "abc-123-def"

'#hasheq((id . "abc-123-def")

(displayName . "Acme Corp")))

• (bc-cache-get entity) — Get cached list endpoint response

• (bc-cache-get entity query) — Get cached filtered list response

• (bc-cache-get entity id) — Get cached single record by ID

• (bc-cache-remove! entity) — Remove list endpoint cache

• (bc-cache-remove! entity query) — Remove filtered list cache

• (bc-cache-remove! entity id) — Remove single record cache

10.3.3 Cache Utilities🔗

Useful for inspecting what’s in the cache.

10.3.4 Cache File Format🔗

Cache files are ".rktd" files (Racket data files) that can be read with read. Each file contains a hash with the structure:

'#hasheq((url . "https://api.businesscentral.dynamics.com/...")

(query)

(cached-at . 1702900000)

(response . #hasheq((value . (...)))))

You can manually create or edit these files to populate the cache with test fixtures. The filename is a SHA-1 hash of the URL and query parameters.

10.5.1 Result Accessors🔗

(bc-result-count (customers-list))  ;; -> 42

(bc-result-ref (customers-list) 0)  ;; -> first customer hash

Use this when you need list operations like filter, map, or length:

(define all-customers (bc-result->list (customers-list)))

(filter (lambda (c) (hash-ref c 'blocked #f)) all-customers)

For simple iteration, prefer for directly on the result (more efficient).

Useful for understanding memory usage of large datasets.

While bc-result implements prop:sequence and can be used directly in for clauses, using in-bc-result is more efficient because it expands at compile time directly to in-vector, avoiding runtime sequence dispatch.

(define result (customers-list))

;; Both work, but in-bc-result is faster:

(for ([c result]) ...)              ; runtime dispatch via prop:sequence

(for ([c (in-bc-result result)]) ...) ; compile-time expansion

10.8.1 Configuration🔗

10.8.2 Environment Discovery🔗

Before connecting to a specific BC environment, you can discover which environments are available for your tenant.

• name — The environment name (e.g., "Production", "Sandbox")

• type — Either "Production" or "Sandbox"

• status — Current status (e.g., "Active", "Preparing")

• aad-tenant-id — The Azure AD tenant ID

• application-family — Usually "BusinessCentral"

• country-code — Two-letter country code (e.g., "US", "DK")

• webClientLoginUrl — URL to access the web client, or #f

• properties — The full API response hash with additional properties

This function uses the Admin Center API, which requires only tenant-level authentication. You must call bc-authenticate! or bc-authenticate/cached! before using this function, but you do not need to set current-bc-environment or current-bc-company first.