API Overview

This overview explains how to access the COSMO Product Data Management APIs for Dynamics 365 Business Central and points to detailed reference pages.

• API style: OData v4 (JSON)
• Versioning: path-based (v2.0)
• Publisher: cosmoconsult
• Group: productdatamanagement

Base URLs

• SaaS (Business Central online)
  • Base: https://api.businesscentral.dynamics.com/v2.0/{tenant}/Production/api/cosmoconsult/productdatamanagement/v2.0
• On-Premises (behind your container/host)
  • Base: https://{host}/{container}rest/api/cosmoconsult/productdatamanagement/v2.0

Replace placeholders with your values:

• {tenant}: Azure AD tenant ID or domain
• {host}/{container}: On-Prem host and server instance

Authentication

Use Microsoft Entra ID (Azure AD) OAuth 2.0 to obtain a bearer token. Include the token in the Authorization header.

• Grant type: client credentials or delegated (depending on your scenario)
• Audience/Scope: Business Central API (for client credentials, use the ".default" scope of the Business Central resource)
• Header example:
  • Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...
  • Content-Type: application/json

For tenant- and app-registration steps, see Business Central Web Services Authentication on Microsoft Learn.

Versioning

• The API version is part of the path, e.g., .../v2.0
• Breaking changes introduce a new version; v2.0 remains stable.

Concurrency and ETags

• PATCH operations require If-Match with the entity ETag (use "*" only for testing).
• Read responses include ETag where applicable.

Query Options

Standard OData options are supported where exposed by the page:

• $select, $filter, $orderby, $top, $skip
• $expand on supported navigation properties (see each resource page)

Change Tracking

• If an entity set supports change tracking, responses will advertise delta links. Follow the delta link to retrieve incremental changes.
• If no delta link is returned, change tracking isn't available for that entity set.

Metadata and Discovery

• Metadata: {Base}/$metadata?tenant=default&$schemaversion=2.0
• Entity sets and schema are discoverable from $metadata. Use it to generate clients or verify properties and navigation.

Example discovery flow

1. GET {Base}/$metadata to inspect resources and actions
2. List an entity set, e.g., GET {Base}/engChangeOrders
3. Use $expand to include related collections where supported

Service Protection Limits

• Business Central applies service protection (throttling) limits to APIs. If you receive 429 responses, back off and retry with exponential delays.
• See Microsoft Learn for the latest numbers and recommendations.

Next Steps

• Endpoints index: API Endpoints Index
• Resource list: API Resources
• ECO task activation event: EngChangeOrderTaskActivated
• Resource reference pages: engChangeNotice, engChangeOrder, engChangeOrderTask, engTaskTemplate, and others in this folder.
• Events list: External Business Events List

OpenAPI Specification Download

Download or reference the OpenAPI (Swagger) specification for tooling (client generation, validation).

• Raw file (YAML): cosmoconsult.productdatamanagement.yaml
• (Optional placeholder for future versions): productdatamanagement-v2.0.yaml (remove once you no longer need a stub)

Usage tips:

• Import into Postman or VS Code REST Client extensions.
• Use openapi-generator / autorest to create client stubs.
• Keep this file updated when endpoints or schemas change (version tag in info section).

Feedback
Submit feedback for this page .