Design considerations
As with all integrations between more than one software system, it is important to design an integration that is efficient, robust, scalable, and stays within API call limits, without hindering overall application performance. Some Condeco endpoints have the potential to retrieve a significant amount of data with just one call, and making too many of these calls too often, can potentially impact the performance of your production Condeco instance and likely result in exceeding the allowed endpoint call count.
Condeco call limits are a maximum 500 per minute/50k per week.
The current set of Condeco endpoints are mostly ‘room centric’ and have a specific purpose, such as creating a single booking via a piece of external hardware such as an Amazon Alexa device or to obtain a list of visitors for a specific date. In the future, Condeco plan to release more generic endpoints, such as pulling booking data for a specific group or location, rather than at the individual resource level.
Where possible, Condeco highly recommends creating a local copy of the data from Condeco and using our ‘Webhooks/Notifications’ to pull through updates and changes to keep data up-to-date, without making hundreds/thousands of calls to check If anything has changed.
Example A
Objective: A location has up to 100 rooms across multiple floors and you want your third-party app to show how many are available.
Option 1: Instead of making a call every minute (approx. 54,000 calls over 9 hours which far exceeds the weekly call limit), we recommend pulling all upcoming bookings for the next 14 days for each room (using the ‘Bookings_GetBookings_V1’ endpoint), storing that data locally, then allowing the ‘Meeting External’ and ‘Meeting Progression’ listener services to update this data when it changes.
A notification is sent with the ‘bookingID’, which can be used to then pull booking information for that specific booking, rather than checking lots of rooms for new bookings that may not exist. Queries can then be executed frequently against the locally stored data to retrieve the required data.
Option 2: Reduce the frequency of the calls to every 10 minutes and restrict calls to only business hours (9 am to 6 pm), bringing the call count to roughly 27,000 per week, which is within the weekly call limit.
This type of integration is known as ‘polling’ and in certain use-cases is sufficient. However, as your Condeco system grows and more resources are added, scalability can be limited, especially when the number of resources is over 150.
Example B
Objective: To use a 3rd party app to create and add desk bookings into Condeco.
We recommend using the ‘DeskBooking_GetDeskBookings_V1’ endpoint to pull all bookings for the next 14 days for every room, store this data locally, restrict search criteria to a specific floor or location, utilize the notification services via Desk and Desk Progression listeners to ensure local data is up-to-date via ‘DeskBooking_GetDeskBookingsByBookingId_V1’ endpoint for any new bookings, and then create a booking for the selected desk via ‘DeskBooking_CreateDeskBooking_V1’.
As the bulk of the data load is done upfront, this type of integration scales easily and provides much greater flexibility without having to be too concerned about hitting the API endpoint weekly call limits.
When using Booking Creation endpoints for both room and desks, the ‘userID’ will need to be retrieved. This can be done by using the ‘Users_GetAllUsers_V1’ endpoint, a list of users can be stored locally or you can use this endpoint to search for a specific user based on email address.
Summary of recommendations
Condeco recommends taking the following points into consideration when utilizing the API:
- Review the purpose of required data, the likelihood of a change to the data, and then limit endpoint call frequency.
- Store data locally.
- Utilize available notification services for better scalability and performance.
- Where possible, enable API calls only during business hours only.