bcnav: Business Central API Client for Racket

1	Introduction
2	Quick Tour
3	Setup & Authentication
4	Querying with OData
5	Working with Entities
6	Metadata Discovery
7	Custom APIs
8	Logging & Debugging
9	Response Caching
10	Core Module Reference
11	OData Query Reference
12	Entity API Reference
13	Metadata Discovery Reference
14	Appendix: Security

On this page:

bcnav: Business Central API Client for Racket

9.3

contents ← prev up next →

bcnav: Business Central API Client for Racket🔗

Joel Dueck

bcnav is a Racket library for working with Microsoft Dynamics 365 Business Central’s REST APIs. It handles OAuth 2.0 authentication, provides a composable query language for filtering and selecting data, and offers a consistent interface for all standard and custom BC entities.

If you’re a Business Central developer or administrator looking to automate tasks, extract data, or build custom integrations, bcnav gives you a powerful interactive environment with the full expressiveness of a real programming language.

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

2.2 Listing records

2.3 Filtering and selecting

2.4 Getting a single record

2.5 Creating records

2.6 Updating records

2.7 Working with related records

2.8 Exploring the schema

2.9 What’s next

3 Setup & Authentication

3.1 Understanding the authentication flow

3.2 Creating an Azure AD app registration

3.2.1 Step 1: Access the Azure Portal

3.2.2 Step 2: Navigate to App registrations

3.2.3 Step 3: Configure basic settings

3.2.4 Step 4: Note your IDs

3.2.5 Step 5: Create a client secret

3.2.6 Step 6: Configure API permissions

3.3 Finding your Business Central company ID

3.4 Understanding Racket parameters

3.5 Storing credentials securely

3.5.1 Environment variables (recommended)

3.5.2 Separate configuration file

3.6 Authenticating with client credentials

3.7 Interactive authentication

3.8 Checking authentication status

3.9 Troubleshooting

3.9.1 AADSTS700016: Application not found

3.9.2 AADSTS7000218: Request body must contain client_secret

3.9.3 401 Unauthorized from Business Central

3.10 Next steps

4 Querying with OData

4.1 The query builder

4.2 Filtering records

4.2.1 Comparison operators

4.2.2 String functions

4.2.3 Logical operators

4.2.4 Building complex filters

4.3 Selecting fields

4.4 Expanding related records

4.5 Sorting results

4.6 Limiting and paginating results

4.7 Composing queries

4.8 Seeing the generated query string

4.9 Common patterns

4.9.1 Find records by partial name

4.9.2 Find records modified recently

4.9.3 Filter by date range

4.9.4 Find records with specific status and amount range

4.9.5 Get lightweight list for a dropdown

4.10 Next steps

5 Working with Entities

5.1 The entity pattern

5.2 Listing records

5.2.1 Using queries

5.2.2 Automatic pagination

5.3 Getting a single record

5.4 Creating records

5.4.1 Discovering available fields

5.4.2 Working with the returned record

5.5 Updating records

5.5.1 Understanding ETags

5.5.2 Update return value

5.6 Deleting records

5.6.1 ETags for deletes

5.7 Handling errors

5.8 Working with entity modules

5.9 Example: Customer management script

5.10 Next steps

6 Metadata Discovery

6.1 The value of interactive exploration

6.2 Inspecting an entity

6.2.1 Understanding the output

6.2.2 OData types

6.2.3 Enum types

6.3 Previewing data

6.3.1 Visual preview with peek

6.3.2 Raw data with sample

6.4 Generating documentation

6.4.1 Racket comment format

6.4.2 Scribble format

6.5 Fetching raw metadata

6.5.1 All standard entities

6.5.2 Individual entity schema

6.5.3 Examining properties

6.5.4 Examining navigation properties

6.6 Metadata caching

6.7 Custom API metadata

6.8 Practical examples

6.8.1 Find entities with a specific field

6.8.2 Find expandable relationships

6.8.3 Generate a type summary

6.9 When metadata helps

6.10 Next steps

7.1 Defining standard API entities

7.2 Understanding BC API URLs

7.3 What macros generate

7.4 Defining a custom API

7.5 Defining entities

7.6 Complete example

7.7 Generated functions

7.8 Inspecting custom entities

7.9 Finding available APIs

7.10 Example: Working with a real publisher API

7.11 Best practices

7.11.1 One module per API

7.11.2 Document your entities

7.11.3 Version your APIs

7.12 Next steps

8 Logging & Debugging

8.1 Enabling logging

8.3 Request logging

8.4 Stopping the listener

8.5 Common troubleshooting scenarios

8.5.1 Authentication failures

8.5.2 API errors (4xx responses)

8.5.3 Rate limiting

8.5.4 Checking your configuration

8.6 Debugging queries

8.7 Inspecting responses

8.8 Using parameterize for testing

8.9 Getting help

9 Response Caching

9.2 Enabling the cache

9.3 Cache modes

9.3.1 Manual mode (default)

9.4 Working with the cache API

9.4.1 Caching list endpoints

9.4.2 Caching filtered queries

9.4.3 Caching individual records

9.4.4 Removing cached data

9.5 Inspecting the cache

9.6 Creating test fixtures

9.6.1 Step 1: Capture real data

9.6.2 Step 2: Use cached data in tests

9.6.3 Step 3: Manually edit fixtures (optional)

9.7 Cache behavior with the HTTP layer

9.7.1 Checking cache status in results

9.8 How the cache works

9.8.1 Path resolution

9.8.2 Automatic directory creation

9.8.3 Disk-only storage

9.9 Best practices

9.9.1 Use separate cache directories

9.9.2 Clear cache when data changes

9.9.3 Be mindful of sensitive data

9.9.4 Use parameterize for isolation

9.10 Troubleshooting

9.10.1 Cache not being used

9.10.2 Stale data

9.10.3 Cache file not found

10 Core Module Reference

10.1 Configuration Parameters

10.2 Behavior Parameters

10.3 Response Caching

10.3.1 Cache Parameters

10.3.2 Entity-Based Cache API

10.3.3 Cache Utilities

10.3.4 Cache File Format

10.4 Authentication

10.5 Result Wrapper

10.5.1 Result Accessors

10.6 Exceptions

10.8 Admin Center API

10.8.1 Configuration

10.8.2 Environment Discovery

11 OData Query Reference

11.1 Query Construction

11.2 Query Accessors

11.3 Query Composition

11.4 Query Conversion

11.5 Filter Expressions

11.5.1 Comparison Operators

11.5.2 String Functions

11.5.3 Logical Operators

11.5.4 Type Wrappers

11.5.5 Date/Time Range Filters

11.5.6 Filter Utilities

12 Entity API Reference

12.1 Master Data

12.1.1 Customers

12.2.1 Sales Orders

12.2.2 Sales Invoices

12.3 Purchasing

12.3.1 Purchase Orders

12.3.2 Purchase Invoices

12.4.1 Accounts

12.4.2 Trial Balance

12.4.3 General Ledger Entries

12.4.4 Journals

12.5 Custom API Framework

12.6 Entity Function Patterns

12.6.1 List functions

12.6.2 Get functions

12.6.3 Create functions

12.6.4 Update functions

12.6.5 Delete functions

13 Metadata Discovery Reference

13.1 Entity Descriptors

13.2 Schema Inspection

13.3 Standard API Metadata

13.4 Custom API Metadata

13.5 Schema Data Structures

13.6 Enum Support

13.7 Cache Management

14 Appendix: Security

14.1 Token storage

14.2 Input handling

14.3 Concurrency and ETags

14.4 The authorization flow

14.5 Sensitive data in memory

14.6 What bcnav doesn’t do

contents ← prev up next →