Microsoft Dynamics On-Premise API Essential Guide

What type of API does Microsoft Dynamics On-Premise provide?

REST API

REST APIs are the recommended and preferred way to integrate with Microsoft Dynamics 365 Business Central (which is part of the Dynamics family):

• The Business Central REST API stack is optimized for performance and is now the preferred way to integrate Business Central with external systems.
• Business Central comes with an extensive list of built-in REST APIs that require minimal setup to use.
• Developers can also create custom REST APIs using API pages and API queries.

OData Web Services

OData web services are also supported:

• Business Central supports OData web services based on OData version 4.
• OData web services can be used for reading data and are supported in Power BI connectors.
• However, OData is considered a legacy method compared to the newer REST APIs.

SOAP Web Services

SOAP web services are supported but being phased out:

• SOAP web services allow publishing pages and codeunits as SOAP endpoints.
• However, SOAP is being replaced by OData V4 and REST APIs.
• Support for SOAP endpoints will be removed in a future release, so Microsoft recommends migrating to OData V4 or REST APIs.

Does the Microsoft Dynamics On-Premise API have webhooks?

Availability of Webhooks

Yes, the official Microsoft Dynamics On-Premise API does have webhooks support. Webhooks were introduced starting with Dynamics 365 for Customer Engagement apps version 9.0.

Types of Events You Can Subscribe To

You can subscribe to various types of events using webhooks in Dynamics 365 On-Premise. Webhooks can be registered for entity-level events, similar to plugin registration. You can specify the message (event type) when registering a webhook step, just like registering a plugin step. Common events you can subscribe to include create, update, delete, and other entity-specific operations. You can specify where in the event pipeline to execute the webhook (pre-operation, post-operation, etc.). Both synchronous and asynchronous execution modes are supported for webhooks.

Key Considerations

Webhooks send POST requests with JSON payload to your specified endpoint. You can secure your webhook endpoint using authentication options like HttpHeader, WebhookKey, or HttpQueryString. Webhooks can be invoked from plugins or custom workflow activities as well. There are limitations on the payload size (256KB) and number of records that can trigger a webhook in certain scenarios.

Implementation

To implement webhooks, you need to create or configure a service to consume webhook requests, register the webhook in Dynamics 365 using the Plugin Registration Tool, and register a step for the webhook, specifying the event, entity, and other parameters.

It's worth noting that while webhooks provide real-time notifications, they may have scalability limitations compared to Azure Service Bus integration for high-volume scenarios.

Rate Limits and other limitations

Based on the search results, here are the key points about API rate limits for Microsoft Dynamics On-Premise API:

1. There are conflicting reports about whether API rate limits apply to on-premise deployments:

   • One source states there are no such limitations for on-premise.
   • However, other sources discuss API limits without specifying if they apply only to online or also to on-premise.

2. For Dynamics 365 online environments, the following limits are enforced per user, per application ID, per web server:

   • 6,000 requests within a 5-minute sliding window
   • 20 minutes (1,200 seconds) of combined execution time within a 5-minute sliding window
   • 52 concurrent requests

3. These limits were introduced in March 2018 for Dynamics 365 Customer Engagement.

4. The limits are designed to protect the service from extraordinary demands that could impact availability and performance.

5. Normal interactive users are not expected to be affected by these limits.

6. Exceeding the limits results in error responses:

   • 429 Too Many Requests for Web API
   • OrganizationServiceFault errors for .NET SDK

7. Some Microsoft services are exempt from these limits, including the Document Routing Agent, Warehouse Management mobile app, Retail Server API, and others.

8. There are also resource-based limits that throttle requests when aggregate server resource utilization reaches certain thresholds.

Key considerations:

• The applicability of these limits to on-premise deployments is unclear from the available information.
• If the limits do apply on-premise, they would be enforced per web server in the deployment.
• Applications should be designed to work within these limits, using strategies like batching requests when dealing with bulk operations.
• Monitoring API usage and implementing appropriate error handling is important for applications integrating with Dynamics.

In summary, while there are well-defined API rate limits for Dynamics 365 online environments, the information about limits specifically for on-premise deployments is inconclusive based on the provided search results. Organizations using on-premise Dynamics should consult their specific documentation or Microsoft support for clarification on applicable API limits.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Microsoft Dynamics On-Premise API:

1. The most recent version mentioned for Microsoft Dynamics 365 On-Premises is version 9.1.

2. For Dynamics 365 Customer Engagement (on-premises), the Web API was introduced with version 8.0 and has achieved parity with the Organization service.

3. The Web API implements the OData (Open Data Protocol) v4 standard.

4. The latest cumulative update for Dynamics 365 (on-premises) version 8.2 is Update 2.28, released in April 2021 with version number 8.2.28.11.

5. For Dynamics 365 Business Central on-premises, the most recent release mentioned is the 2023 release wave 2.

Key points to consider:

• The Web API is recommended as the first choice for new development that will support Dynamics 365 Customer Engagement (on-premises) and future versions.

• The Web API provides better compatibility across a wide variety of programming languages, platforms, and devices compared to the Organization service.

• For code running on the server, such as plug-ins or workflow assemblies, it's still recommended to use the Organization service.

• The Web API supports version-specific differences in the same environment, allowing for ongoing improvements and potentially breaking changes.

In summary, while the most recent major version mentioned is 9.1 for Dynamics 365 On-Premises, the Web API (which was introduced in version 8.0) is the recommended API for new development. It's important to note that the specific version and updates may vary depending on the exact Dynamics 365 product and deployment type you're working with.

How to get a Microsoft Dynamics On-Premise developer account and API Keys?

1. Set up a Dynamics 365 On-Premise environment

• Install Dynamics 365 Customer Engagement (on-premises) on your own servers or use a hosted environment.

2. Enable web services

• Web services are not enabled by default for on-premises deployments. An administrator needs to enable them.

3. Create a developer account

• Create a user account in Dynamics 365 with the necessary security roles and permissions to access the APIs you need.

4. Generate a web service access key

• For the developer account, generate a web service access key that will be used for authentication.

5. Choose an authentication method

• For on-premises, you can use:
  • Basic authentication with username and web service access key
  • Microsoft Entra ID (Azure AD) authentication (recommended for production)

6. Determine the API endpoint

• The endpoint URL will be in the format: https://<base URL>:<port>/<serverInstance>/api/<API version>/ For example: https://nav.contoso.com:7048/bc/api/v2.0

7. Set up your development environment

• Install necessary SDKs and tools for the programming language you'll use
• Configure your API client to use the correct endpoint and authentication

Key points to consider:

• Basic authentication is deprecated for SaaS deployments but may still be used for on-premises.
• For production use, Microsoft Entra ID authentication is recommended.
• Ensure you have the necessary permissions configured for your developer account.
• Familiarize yourself with the available APIs and their capabilities.

What can you do with the Microsoft Dynamics On-Premise API?

Based on the search results provided, here is a list of data models that can be interacted with using the Microsoft Dynamics On-Premise API, along with what is possible for each:

Web API

• Introduced with version 8.0 and provides parity with the Organization service
• Allows interaction with various data entities in Dynamics 365 Customer Engagement (on-premises)
• Supports CRUD (Create, Read, Update, Delete) operations on data entities
• Implements OData (Open Data Protocol) v4 standard
• Better compatibility across programming languages, platforms, and devices
• Can be used for projects accessing Dynamics 365 data with code that doesn't run on the server
• Suitable for web resources and form scripts running in Dynamics 365 application clients

Organization Service

• Optimized for use with .NET
• Provides access to various data entities and business logic in Dynamics 365
• Supports CRUD operations and specialized messages
• Can be used with .NET assemblies and tools to generate strongly typed classes and proxies
• Suitable for server-side code, such as plug-ins or workflow assemblies
• Supports older versions of Dynamics 365 Customer Engagement (on-premises)

Discovery Web Services

• Allows detection of available servers and organizations for a user to connect to
• Can be accessed using either the OData V4-based Web API or the SDK assembly API
• Provides functionality to discover the URL for a user's organization

Data Management Framework REST Package API

• Supports interaction with data packages (collections of data entities)
• Allows import or export of data packages as a unit
• Suitable for large-volume integrations
• Supports change tracking and on-premises scenarios
• Enables asynchronous, batched data operations

Recurring Data Management Integration REST API

• Supports scheduling recurring integration of files and packages
• Allows large-volume integrations of files and packages
• Supports recurrence scheduling and transformations inside Dynamics 365 apps
• Compatible with both cloud and on-premises scenarios

Custom Services

• Allows creation and exposure of custom web services using X++
• Supports SOAP, REST, and JSON formats
• Enables invocation of actions or data updates using custom logic
• Suitable for high-volume integrations with reduced overhead compared to other options

Business Events

• Provides a mechanism for external systems to receive notifications from finance and operations apps
• Enables integration across products and platforms using events capturing user or system actions
• Can be used with Azure Event Grid, Power Automate, or Logic Apps

Virtual Tables (for finance and operations apps)

• Allows connection of Dataverse to finance and operations app entities as virtual tables
• Supports full CRUD capabilities on these virtual entities
• Enables secure and consistent access to data that looks and behaves like regular Dataverse tables
• Can be used with Power Automate for connecting to other sources

By leveraging these various data models and APIs, developers can interact with a wide range of data and functionality within the Microsoft Dynamics On-Premise ecosystem, enabling complex integrations and customizations to meet specific business needs.