Appointment API requirements and questions

This forum is for programmers who have questions about the source code.
Post Reply
azzedine
Posts: 5
Joined: Mon Aug 19, 2013 3:24 pm

Appointment API requirements and questions

Post by azzedine » Thu Feb 11, 2021 10:25 am

Hi,

I'm working on some plugins/integration and I decided to look at the recommended way which seems to be using the API : https://www.opendental.com/resources/OpenDentalAPI.pdf

It seems the API server is not local and it will be routed via the OD servers, does this mean the practices need to be on a support plan or have e-services activated for it to work ?

The API doesn't seem to enable the creation of new patients or updates to existing appointments which is causing me the following issues:

- #1 How do I go via the current API to create a new patient and schedule them ?
- #2 How would I update the status of their appointment to confirmed once they do via email/sms ?

For #1 my current idea would be create an patient at setup (say "Online Services") so I know this patientID and just assign new appointments to this "fake" patient but then can I add some meta data to the appointment (POST /appointments) to have the actually data for the new patient and let the OD user add it manually ? More specifically when I do POST /appointments can I push some data inside "Notes" or any other field ?

For #2 I have no idea :d

Looking at the API, I understand why most people poke the DB directly it's easier and supports a lot more options :/

sammyp42
Posts: 23
Joined: Wed Jun 04, 2014 12:55 pm
Location: Redwood City, CA

Re: Appointment API requirements and questions

Post by sammyp42 » Thu Feb 11, 2021 10:57 am

The API goes through OD servers for security. You never want an external service (API client) to hit your servers directly, that's BAD!

I do have to concur that it seems easier to run with your custom API / plugin than having to wait for API functionality (which you possibly have to pay extra for). I would be delighted if the new API came free with the basic support plan, or bundled free with the "Mobile Web" eService option. This would make migrating to it feasible and practical.

User avatar
jordansparks
Site Admin
Posts: 5739
Joined: Sun Jun 17, 2007 3:59 pm
Location: Salem, Oregon
Contact:

Re: Appointment API requirements and questions

Post by jordansparks » Thu Feb 11, 2021 11:09 am

They don't need to be on e-services. I think they might need to be on support, and I think we charge a little bit for use of the API. It just doesn't seem possible to expect a customer to maintain their own web server. This was the only way we could think of to make it a really smooth experience.

I just posted an updated PDF documentation.
#1 see POST /patients and POST /appointments. But your idea of having a dummy patient that gets reused isn't terrible. I just don't know where you would put the name, etc. To know where there are openings, you will also need GET /appointments/GetSlots, which is not yet documented. Yes, when you POST /appointments, you can include a Note.
#2 PUT /appointments/Confirm and probably also POST /commlogs

Writing directly to the database has always been forbidden, although changing appointment confirmed status has been a gray area that we have let slide so far. That will be coming to an end. Not immediately, because we don't want to break any existing tools, but it must end. It's just far too dangerous. Of course, we can't start clamping down until we have fully functional alternatives. That's why we're working so hard on the API.
Jordan Sparks, DMD
http://www.opendental.com

User avatar
jordansparks
Site Admin
Posts: 5739
Joined: Sun Jun 17, 2007 3:59 pm
Location: Salem, Oregon
Contact:

Re: Appointment API requirements and questions

Post by jordansparks » Thu Feb 11, 2021 11:15 am

I've been thinking really hard about how to charge for this. Flat fee is easier to manage. Low/free is obviously better if we can figure out how. Adding a few appointments would be a very low load on our servers, but I can also see how someone might start hitting us with read requests at a furious pace if it was inside a loop or something. So throttling might be a way to lower the fee. Maybe even severe throttling, like one request allowed per minute, might be enough to make it free.
Jordan Sparks, DMD
http://www.opendental.com

azzedine
Posts: 5
Joined: Mon Aug 19, 2013 3:24 pm

Re: Appointment API requirements and questions

Post by azzedine » Thu Feb 11, 2021 12:30 pm

Thanks for the quick response sammyp42 and Jordan.

I totally understand the reasons to not host and expose it externally from the offices. However, there could be a couple of workaround I can think of:
- Locally hosted REST API, that a local service could interact with (and then sync to the cloud)
- An exposed API (not REST)/ SDK where you would expose the basics functions for appointment list/create/update this way the OD team would basically handle the way this calls are touching the database and would be able to ensure all is done according to their standard.

Jordan thanks a lot for the updated documentation, the /appointments/GetSlots is saving me some time. I was going to implement it based on the return value of GET /appointments with date as parameter. Also thank you for thinking about the fee/charge model for this. If you use an API gateway like Apigee or Kong (or even the AWS api gateway) it's pretty easy to ensure throttling and other secure measure to avoid high usage.

User avatar
jordansparks
Site Admin
Posts: 5739
Joined: Sun Jun 17, 2007 3:59 pm
Location: Salem, Oregon
Contact:

Re: Appointment API requirements and questions

Post by jordansparks » Thu Feb 11, 2021 3:22 pm

Customer does not need to be on support to use the API. The API isn't intended for direct customer use, but is only intended for 3rd party companies that are building integrations. Keeping that in mind, we probably won't have anything for free. We're probably looking at $10/month to cover a variety of scenarios, and rarely a slightly higher rate to cover highly complex integrations. Development and testing environments can be free. The 3rd party integrators are not unknown to us. We have conversations with each of them about how they will be using the API.
Your suggestion for a non-REST SDK is interesting. I can't think of a good reason not to do it other than we don't have time to do everything. We keep running into scenarios where on-site software is not as desirable as cloud. So, we're naturally more focused on the decentralized API to support more scenarios.
Jordan Sparks, DMD
http://www.opendental.com

Post Reply