Blue Point Brewing, a Long Island craft beer brewery, decided to open their new Brew Pub in downtown Patchogue with a digital food and beer ordering concept. The goal was to update the idea of a “traditional restaurant”, with a digital experience that is easy to use and seamlessly integrated in the restaurant processes.
Blue Point partnered with Toast, a restaurant point of sale and management system. For the digital ordering experience, Ballast Lane used Toast API structures but developed a customized NodeJS backend solution around it to facilitate a unique customer ordering and admin frontend. The customer-facing order solution is a responsive website built in ReactJS.
Integration with Toast
Ballast Lane used the following APIs:
- Orders v2 Read: To get the prices for items of an order and display those on the order screen for the customer
- Orders v2 Write: To place a customer’s order in the toast system, once the customer confirms the order on their checkout page
- Configuration v2: To get all available tables listed in toast, display those in the admin frontend and manage display on the customer order website
- Orders v2 Read:Orders v2 Read: To get the menu items outside of Toasts regular daily menu exports from AWS S3
- Restaurant v1: To get the restaurant opening hours
- Credit Cards API Write: To charge customers using their credit card, without storing the credit card information on Ballast Lane servers
More custom features
On top of the existing API structure, Ballast Lane built some interesting custom features for Blue Point Brewing to allow for more flexibility in the menu and process handling:
- Menu updates: Time-sensitive updates are able to be made to the menu at any time, outside of Toast’s fixed daily update cycles
- Table management: The option to enable/disable tables to show in the customer order frontend depending on customer traffic in the restaurant
- Enriched menu item information: Additional information on beers can be added using the admin frontend, to add filters to the customer ordering frontend
- Loyalty program: Customized loyalty program, with the ability to update the point-based system on Admin frontend
In the process of developing an integrated backend with Toast, Ballast Lane gained a number of insights that are very helpful for any developer who wants to integrate with Toast APIs.
Here are the three top points from Raul Neis, lead backend developer for the project, to keep in mind:
1. You have to adapt menu structures
Every system has its own data structures to meet the specific goals and needs. This is true even for systems within the same domain.
For instance, Toast API has a multilevel menu structure, which is good for their goals, but we actually wanted to keep it simple, so we didn’t need that. For that reason, it was better for our frontend to receive the whole menu all at once. We had to adapt the data structure Toast provided us to fit our needs. In addition, we also required additional information about beers, therefore we added those structures on our side.
Another requirement we had was to offer different menu items depending on the time of the day. Toast offers an API for attention hours, but we had to figure out a way to adapt that functionality to support this custom requirement.
2. Caching is important
Querying an external API is time-consuming, so it’s better to cache data as much as possible. Sometimes it is even mandatory to do so in order to deliver a good user experience.
It’s not that the Toast API is slow, but every external request can take from tens to hundred of milliseconds. If we need to perform one or more request for every interaction with the customer, it will take more time than what’s acceptable for a great user experience. So we used cache every time it was suitable.
For things that need to be kept synchronized, it was not suitable. For other things we used short periods of time to improve perceived performance e.g., list of tables. And for other things that usually don’t change, we used long term caches e.g., opening hours.
3. Develop with APIs rate limits in mind
An example of this is the Toast API access token. They can be requested no more than twice an hour, and they usually last for about an hour. So we had to store those tokens, and only require new ones if necessary. For Toast, this is a soft limit (they don’t enforce it) but it is always good to be a good API consumer.
We also developed some processes for the application that perform a lot of requests in short periods of time. To account for Toast API limits, we designed our processes to cache everything possible, as mentioned above (this way we avoided sending some requests) but we also developed our system to properly handle rate limit situations, and reschedule requests to Toast in those cases.
