Part 1 of 4: The Product Catalog API
The Beginning: A Growing Business Drowning in Paper
Rajesh Mehta stared at the mountain of notebooks piled on his desk. Each one represented a different aspect of his thriving gift shop in Mumbai – customer records, inventory logs, sales receipts, loyalty points. What started as a manageable system for 20 customers had become an overwhelming mess with 500 customers and 200+ products.
The breaking point came when Mrs. Sharma, one of his most loyal customers, called asking about her purchase history. Rajesh spent 45 minutes flipping through notebooks, only to give up in frustration. He knew something had to change.
Enter Rohan, a Business Central AL developer who specialized in helping traditional businesses embrace digital transformation. After implementing Microsoft Dynamics 365 Business Central, Rajesh’s world changed overnight. Customer data, inventory, and sales were now at his fingertips.
But the real transformation was yet to come.
The Challenge: Bridging Digital Islands
Six months into using Business Central, Rajesh faced a new challenge. His son Arjun wanted to launch an e-commerce website. The sales team needed a mobile app. Customers wanted to check loyalty points on WhatsApp. Each system needed the same data – products, prices, inventory, and customer information.
Manually syncing data across multiple platforms was impossible. Re-entering the same information multiple times would recreate the chaos Rajesh had just escaped.
The solution? Business Central APIs – digital bridges that would connect all systems seamlessly.
Understanding APIs: The Digital Messenger System
Before diving into code, let’s understand what APIs do.
Think of Business Central as a secure vault containing your business data. APIs are like authorized tellers at a bank window – they take requests, fetch the required information from the vault, and deliver it back securely. They allow external applications to communicate with Business Central without exposing the entire database.
Key Components
Endpoint – The URL address where the API lives: https://api.businesscentral.dynamics.com/v2.0/production/api/mehtagifts/shop/v1.0/companies(company-id)/products
HTTP Methods
The types of operations you can perform:
- GET – Retrieve data (reading)
- POST – Create new records (adding)
- PATCH – Update existing records (modifying)
- DELETE – Remove records (deleting)
Request/Response
The conversation format:
- Request – What you ask for (with headers and sometimes data)
- Response – What you get back (usually in JSON format)
Building the Foundation: Product Catalog API
The Business Need
Arjun’s e-commerce website needed to display all 200 products with real-time prices and inventory. Manually updating the website every time something changed in the shop was not feasible.
The Technical Solution
Rohan created an API page in Business Central using the AL language. This would expose product data through a standardized REST API endpoint.
Step 1: Creating the API Page
page 50100 "Mehta Product API"
{
// API Configuration
PageType = API;
APIPublisher = 'mehtagifts';
APIGroup = 'shop';
APIVersion = 'v1.0';
EntityName = 'product';
EntitySetName = 'products';
SourceTable = Item;
DelayedInsert = true;
ODataKeyFields = SystemId;
layout
{
area(content)
{
repeater(Group)
{
field(id; Rec.SystemId)
{
Caption = 'ID';
Editable = false;
}
field(itemNo; Rec."No.")
{
Caption = 'Item Number';
}
field(description; Rec.Description)
{
Caption = 'Description';
}
field(description2; Rec."Description 2")
{
Caption = 'Extended Description';
}
field(unitPrice; Rec."Unit Price")
{
Caption = 'Unit Price';
}
field(inventory; Rec.Inventory)
{
Caption = 'Current Stock';
Editable = false;
}
field(itemCategoryCode; Rec."Item Category Code")
{
Caption = 'Category';
}
field(unitOfMeasure; Rec."Base Unit of Measure")
{
Caption = 'Unit';
}
field(lastModifiedDateTime; Rec.SystemModifiedAt)
{
Caption = 'Last Modified';
Editable = false;
}
}
}
}
}Code Explanation
PageType = API – Declares this as an API page, not a regular UI page
APIPublisher, APIGroup, APIVersion – These form the API route structure:
/api/{publisher}/{group}/{version}/
EntityName vs EntitySetName:
- EntityName: Singular, used for single record operations
- EntitySetName: Plural, used for collection operations
SourceTable = Item – Links the API to the standard Business Central Item table
ODataKeyFields = SystemId – Uses the unique GUID as the primary identifier for API operations
DelayedInsert = true – Ensures data validation happens before database insertion
Editable = false – Fields like ID and inventory are read-only through the API
Publishing Your API
What are Web Services?
Web services allow external applications to communicate with Business Central. Think of them as windows through which other software can view and interact with your Business Central data. Web services are of two types:
- SOAP Web Services – Older, more rigid format
- REST APIs – Modern, flexible format (recommended)
Publish the Page as Web Service
In Business Central (for SOAP):
- Search for “Web Services”
- Click New
- Fill in:
- Object Type: Page
- Object ID: 50100
- Service Name: Products (no spaces, use CamelCase)
- Check Published box
- Click OK
Your web service is now available! Get the URLs.
In Business Central (for REST APIs):
- Open Web Services page
- Find your service
- Copy the OData V4 URL (for REST APIs)
API Endpoint Structure
Once published, the API becomes accessible at:
GET https://api.businesscentral.dynamics.com/v2.0/production/api/mehtagifts/shop/v1.0/companies(12345678-1234-1234-1234-123456789abc)/products
Breaking down this URL:
- v2.0 – Business Central API version
- production – Environment name (could also be ‘sandbox’)
- mehtagifts – API Publisher
- shop – API Group
- v1.0 – Your API version
- companies(guid) – Company identifier
- products – Entity set name
Testing Your Product API
Retrieving All Products
Request:
GET /api/mehtagifts/shop/v1.0/companies(company-id)/products
Authorization: Bearer {access-token}
Response:
{
"@odata.context": "https://api.businesscentral.dynamics.com/v2.0/production/api/mehtagifts/shop/v1.0/$metadata#companies(company-id)/products",
"value": [
{
"@odata.etag": "W/\"JzQ0O0VnQUFBQUo3QlRVQU1BQXdBREFBTUE7MDA7Jw==\"",
"id": "5f8a7b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
"itemNo": "GIFT001",
"description": "Decorative Diya Set",
"description2": "Traditional brass diya set of 12 pieces",
"unitPrice": 450.00,
"inventory": 25,
"itemCategoryCode": "FESTIVAL",
"unitOfMeasure": "SET",
"lastModifiedDateTime": "2024-10-15T14:30:00Z"
},
{
"id": "6a9b8c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"itemNo": "GIFT002",
"description": "Crystal Photo Frame",
"description2": "Premium crystal photo frame 6x8 inch",
"unitPrice": 890.00,
"inventory": 12,
"itemCategoryCode": "GIFTS",
"unitOfMeasure": "PCS",
"lastModifiedDateTime": "2024-10-14T09:15:00Z"
}
]
}Advanced Querying with OData
Business Central APIs support OData query parameters, giving you powerful filtering and sorting capabilities.
Filtering Products
- Get products by category: GET /products?$filter=itemCategoryCode eq ‘FESTIVAL’
- Get products with low stock: GET /products?$filter=inventory lt 10
- Get expensive items: GET /products?$filter=unitPrice gt 500
- Combining filters: GET /products?$filter=itemCategoryCode eq ‘GIFTS’ and unitPrice gt 500 and inventory gt 0
Selecting Specific Fields
Instead of retrieving all fields, select only what you need:
GET /products?$select=itemNo,description,unitPrice,inventory
This reduces payload size and improves performance.
Sorting Results
- Sort by price (descending): GET /products?$orderby=unitPrice desc
- Sort by name (ascending): GET /products?$orderby=description
Pagination
For large datasets, use pagination:
GET /products?$top=20&$skip=40
This retrieves 20 products, starting from the 41st record (page 3).
Retrieving a Single Product
When you need details for a specific product:
Request:
GET /products(5f8a7b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c)
Authorization: Bearer {access-token}
Response:
{
"@odata.etag": "W/\"JzQ0O0VnQUFBQUo3QlRVQU1BQXdBREFBTUE7MDA7Jw==\"",
"id": "5f8a7b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
"itemNo": "GIFT001",
"description": "Decorative Diya Set",
"description2": "Traditional brass diya set of 12 pieces",
"unitPrice": 450.00,
"inventory": 25,
"itemCategoryCode": "FESTIVAL",
"unitOfMeasure": "SET",
"lastModifiedDateTime": "2024-10-15T14:30:00Z"
}Real-World Integration: The E-Commerce Website
With the Product API operational, Arjun built his e-commerce website. Here’s a simplified example of how the website fetches and displays products:
// Fetch products from Business Central
async function loadProducts() {
const apiUrl = 'https://api.businesscentral.dynamics.com/v2.0/production/api/mehtagifts/shop/v1.0/companies(company-id)/products';
try {
const response = await fetch(apiUrl, {
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
displayProducts(data.value);
} catch (error) {
console.error('Failed to load products:', error);
}
}
// Display products on the website
function displayProducts(products) {
const container = document.getElementById('products-grid');
products.forEach(product => {
const productCard = `
<div class="product-card">
<h3>${product.description}</h3>
<p>${product.description2}</p>
<p class="price">₹${product.unitPrice}</p>
<p class="stock">${product.inventory} in stock</p>
<button onclick="addToCart('${product.id}')">
Add to Cart
</button>
</div>
`;
container.innerHTML += productCard;
});
}The Immediate Impact
Within the first week of deploying the Product API:
- Website went live with all 200 products displayed accurately
- No manual data entry needed – products automatically synced
- Inventory updates reflected on the website within seconds
- Price changes made in Business Central appeared instantly online
- Customer satisfaction improved as product information was always accurate
Rajesh could now update products once in Business Central, and all channels – website, mobile app, and physical store – would display the same information automatically.
What’s Next?
In Part 2 of this series, we’ll explore how to create and update products through the API, including:
- Using POST requests to add new products
- Bulk product uploads with PowerShell
- Updating prices with PATCH requests
- The famous Diwali sale automation story
- Error handling and validation
The foundation is set. The Product API is operational. But we’ve only scratched the surface of what’s possible with Business Central APIs.
Coming Up in Part 2: “Managing Data Through APIs: Creating, Updating & Bulk Operations” – where we’ll see how Arjun uploads 50 new products in minutes and how Rajesh automates his Diwali sale pricing for 80 products with a single script.