▼bcnav:   Business Central API Client for Racket
►1 Introduction
On this page:
1.1 Why Racket for Business Central?
1.2 What bcnav provides
1.2.1 Authentication
1.2.2 A query language
1.2.3 Entity operations
1.2.4 Metadata discovery
1.2.5 Custom API support
1.3 What you’ll need
1.4 Getting started
9.3
    contents    up   

1 Introduction🔗

1.1 Why Racket for Business Central?🔗

If you work with Business Central, you probably spend time on tasks like:

  • Extracting data for reports or analysis

  • Bulk updates across many records

  • Automating repetitive workflows

  • Integrating BC with other systems

  • Exploring the API to understand available data

You might do these with Power Automate, custom AL extensions, or third-party tools. But each approach has trade-offs: Power Automate can be clunky for complex logic; AL extensions require deployment cycles; third-party tools might not fit your exact needs.

bcnav offers a different approach: direct access to BC’s APIs from an interactive programming environment. You get a full-featured language (Racket) with an immediate feedback loop (the REPL), which makes it easy to:

  • Experiment with API calls and see results instantly

  • Build up complex queries incrementally

  • Write reusable scripts you can run on demand

  • Handle edge cases with real programming constructs

  • Debug problems interactively

1.2 What bcnav provides🔗

1.2.1 Authentication🔗

bcnav handles OAuth 2.0 authentication with Azure AD, supporting both:

  • Client credentials flow — for automated scripts and service-to-service calls

  • Interactive flow — for user-context operations that open a browser for login

Once authenticated, bcnav automatically manages your access token, including refreshing it when it expires.

1.2.2 A query language🔗

Business Central’s API uses OData, a standard for RESTful APIs that supports filtering, field selection, and related-record expansion. bcnav provides a Racket-native way to build these queries:

(customers-list
  #:query (make-query
            #:filter (and: (eq 'blocked #f)
                     (contains 'displayName "Contoso"))
            #:select '(id displayName email)
            #:top 10))

This is more readable than raw OData query strings, and your editor can help you catch mistakes before you run the query.

1.2.3 Entity operations🔗

Every BC API entity follows the same pattern in bcnav:

The same pattern applies to vendors, items, sales orders, invoices, and every other standard BC entity.

1.2.4 Metadata discovery🔗

Not sure what fields an entity has, or what you can expand? bcnav can fetch and parse BC’s metadata schema:

(inspect customers)     ;; view schema
(peek customers)        ;; preview actual data as a table

inspect displays a formatted summary of the entity’s properties, types, and navigation properties. peek fetches and displays actual records as a formatted table—useful when you’re exploring an unfamiliar part of the API.

1.2.5 Custom API support🔗

If your BC installation includes custom or publisher APIs (beyond the standard v2.0 API), bcnav provides macros for defining access to those as well.

1.3 What you’ll need🔗

To use bcnav, you’ll need:

  • Racket — the programming language and environment. Download from racket-lang.org.

  • An Azure AD app registration — this gives you the credentials to authenticate with BC’s API. We’ll walk through setting this up.

  • Access to a Business Central environment — either a production tenant, a sandbox, or a Docker-based development environment.

You don’t need to be an experienced Racket programmer. This documentation explains Racket concepts as they come up, and the interactive REPL makes it easy to experiment and learn.

1.4 Getting started🔗

Continue to the Quick Tour to see what working with bcnav looks like, or jump to Setup & Authentication if you’re ready to set up your credentials.

    contents    up