API Guide - The API Service

For requests or help with our API
Post Reply
SLeon
Posts: 476
Joined: Mon Mar 01, 2021 10:00 am

API Guide - The API Service

Post by SLeon » Thu Jan 19, 2023 10:23 am

The API Service is a lightweight instance of the Remote API that continuously runs on a machine at the dental office. It works by opening a specific port (30223) and listening for API requests made to this machine by any device on the network. The service is installed and started automatically for customers with the API enabled. Like the eConnector, the API Service is kept up to date automatically when updating Open Dental. It is available to dental offices with Open Dental version 22.2 and later.

While it does require some additional setup, there are two main advantages of using the API Service versus the Remote API:
  • Internet Access. The API Service makes a web call to Open Dental HQ to validate credentials once every 6 hours. Subsequent API requests made in this window do not require internet access.
  • Speed. Because each API request is handled within the dental office’s network and does not require traveling to Open Dental’s API servers, total request time is significantly reduced.
Most developers will prefer to use the API Service when available. Requests are 10-20 times faster than using the Remote API endpoint and is ideal for offices with unreliable internet connection.

Installation

The API Service is installed via the OpenDentalAPIService.exe that is included with Open Dental. This occurs automatically for customers who have the API enabled. Manual installation is not necessary for most implementations, however steps can be found here. It is strongly recommended that this is installed on the same server as the dental office’s eConnector.

One Time Setup

API Requests can be made to the server running the API Service by any device on the network. Create an Inbound Rule in Windows Firewall for Port 30223. If it is already running, restart the API Service after creating this rule.

Utilization

Once installed, the API Service can be used in nearly exactly the same way as the Remote API. The only difference in the request formatting is the endpoint. Instead of “https://api.opendental.com/api/v1/...”, requests can be made to the following: Note that only the third endpoint can be used by workstations other than the machine running the API Service.

We recommend developers utilize a “waterfall” strategy of API endpoints for their application. Most implementations will prefer to use the API Service but will be programmed in such a way to use the Remote API instead if the API Service were unavailable at the dental office (their server is offline, etc).

Advanced Users

The API Service can send database ApiEvents. Simply set the machine running the API Service as the Workstation field in your Subscription. Note that duplicate events will fire if both the API Service and an instance of Open Dental are running on the same machine. UI events cannot be sent via the API Service as it does not have a user interface. See our guide on this topic.

A single dental office can have multiple API Services installed on its network. This is unnecessary for API related purposes but may be done by the dental office’s IT as part of their network or database management system. It would be their responsibility to point different users or applications to the different servers running the API Service.

A possible example of this would be a dental office using two third party applications: One for data analytics and another for appointment scheduling. The data analytics software could point to the office’s Reporting or Read-Only server while the appointment scheduler would point to the same server as in-office workstations.

Troubleshooting

Unable to install the API Service.
  • Open Dental must be run as Administrator when installing the API Service.
The API Service is not installed by default for the customer.
  • Ensure the API is enabled at the Dental Office (Setup > Advanced Setup > API). It can be installed manually.
The API Service will not start.
  • This is usually the result of invalid SQL credentials entered at the time of installation. More information on this error can be found in the API Service logs (located \\OpenDental\OpenDentalAPIService\Logger). Change your SQL credentials by un/reinstalling the API Service and entering the correct SQL details when prompted.

Post Reply