RTN’s Open API Framework • Defines API architecture for the restaurant industry • Provides public avenue for adopting best practices • Offers data dictionary for the most common integration needs
|1|
RTN’S OPEN API FRAMEWORK
www.restauranttechnologynetwork.com
Introduction RTN’s Open API Workgroup brought restaurants and suppliers together over a span of nearly two years to develop the industry’s first Open API Framework. The Open API workgroup cited, with overwhelming consensus, that restaurant technology innovation has been stifled by integration challenges, resulting in increased time-to-market, wasted developer, accounting, marketing and operations resources, and lost business capabilities. RTN’s Open API Framework defines key principles and best practices that constitute an Open API, and allows the restaurant industry to embrace a better way forward towards more seamless integration - where the best solutions rise to the top, and restaurants are unencumbered by disparate systems.
Staff
ABBY LORDEN VP and Brand Director, HT Co-Founder, RTN 973.607.1358 alorden@ensembleiq.com
ANNA WOLFE
ANGELA DIFFLY
MICHAL CHRISTINE ESCOBAR
Senior Editor, HT 207.773.1154 awolfe@ensembleiq.com
Co-Founder, RTN 404.550.7789 angela@restauranttechnologynetwork.com
Senior Editor, HT 224.632.8204 mescobar@ensembleiq.com
PATRICK DUNPHY
KATHERINE WARE
CIO, HTNG & RTN 312.690.5039 patrick@restauranttechnologynetwork.com
Senior Account Executive, HT & RTN 785.424.7392 kware@ensembleiq.com
KIRSTEN PHILLIPS
NOELL DIMMIG
Marketing and Membership Manager, HT & RTN 812.322.0681 kirsten@restauranttechnologynetwork.com
ROBERT FIRPO-CAPPIELLO Editor in Chief, HT 917.208.7393 rfirpo-cappiello@ensembleiq.com
RESTAURANT TECHNOLOGY NETWORK
|2|
Account Executive, HT & RTN 973.607.1370 ndimmig@ensembleiq.com
Table of Contents Introduction ........................................................................................................................... 2 Key Contributors....................................................................................................................4 Executive Summary..............................................................................................................5 Self-Service Sign Up for API Partners............................................................................8 Public Facing Documentation...........................................................................................8 Standardized Terms, SLAs and Business Models......................................................8 Testing & Sandbox Environments..................................................................................10 Validation and Certification.............................................................................................10 Extensibility, Enhancements, Flexibility & Updates................................................. 11 Re-Use of Best Practice Data Models........................................................................... 11
RTN Mission The Restaurant Technology Network (RTN) is a membership community solely dedicated to the restaurant technology industry. Through access to valuable benefits and powerful connections, our members shape industry standards and share technical guidance to help restaurateurs run successful businesses and better serve their customers.
Copyright 2021 Restaurant Technology Network (RTN). All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopy, recording or information storage and retrieval systems, without express written permission from the publisher. RTN is a wholly owned subsidiary of EnsembleIQ, with principal headquarters at 8550 W. Bryn Mawr Ave., Suite 200, Chicago, IL 60631.
|3|
RTN’S OPEN API FRAMEWORK
Key Contributors
RESTAURANT TECHNOLOGY NETWORK
|4|
RTN’s Open API Framework • Defines an ideal API architecture and its benefits for the industry • Describes optimal integration business processes & models that reduce time-to-market • Provides an industry focused, public way for companies to adopt best practices • Developed a baseline data dictionary for the most common integration needs This will reduce the amount of time it takes to integrate with a potential partner, the risks associated with onboarding new systems, the complexity of integration, and produce a vibrant ecosystem of suppliers to the restaurant industry.
Executive Summary An Open API architecture at an industry level enables a frictionless integration at a technology, business and process level. Restaurant industry stakeholders achieve value by adopting this framework through: • Minimizing upfront investments in time and resources • Moving from batch, or fragmented analysis to real-time • Creating a level playing field for incumbents and new industry participants • Reducing complexity of change • Increasing the velocity of successful integrations, partners and customers • Lowers the barrier of entry for new industry participants • Reduced support costs • Increases the value of open systems in the buying cycle • Simplifying complex business agreements The key tenants of the Open API Framework for the Restaurant Industry are described below. Restaurants may use the following principles to demonstrate requirements for technology providers in the industry. Technology suppliers should use the following tenants to inform their product roadmap and respond to industry needs.
|5|
RTN’S OPEN API FRAMEWORK
8 Key Principles RTN brought restaurants and suppliers together over a span of two years to develop the restaurant industry’s first game-changing Open API Framework, cemented in these eight foundational principles.
Standardized Terms & SLAs Easily understood terms, requirements and expectations across all levels of support and agreements.
Extensibility, Enhancements, Flexibility & Updates The API must be actively supported with an appropriate roadmap (including end-of-life announcements).
Pricing & Business Model Transparency
Validation and Certification
Pricing and business models are easily understood and predictable.
RESTAURANT TECHNOLOGY NETWORK
Business partners must be able to audit & verify connectivity and appropriate usage.
|6|
Public-Facing Documentation Thorough, easily accessible public information about how to access, consume, and receive support for the API.
Self-Service Sign-Up for API partners An easily accessible, straightforward process to initiate the integration project, which may include automated product API access. This may include API publishers or subscribers.
Testing / Sandbox Environments Appropriate and easily accessible testing suites utilizing commonly available tools.
Re-Use of Best Practice Data The API should use standardized data models across functions, where possible.
|7|
RTN’S OPEN API FRAMEWORK
Self-Service Sign Up for API Partners Searching for and engaging with a potential API partner should be a straightforward process. Clearly-defined requirements for integrations, credentials, and a project-style pathway to full-fledged integration allows potential partners and customers to more easily understand capabilities in an at-a-glance approach, removing stumbling blocks from the overall API integration process. Taken one step further, the entire process could be automated to follow this RACI & project plan matrix. Outcomes of an Open API-centric approach to self-service signup include, but are not limited to: •
Automated external access to basic API capabilities, including testing environments
•
Up-front licensing, documentation, and end-user agreement statements
•
Ability to request support from a common portal
•
Ability to upgrade an account from one type to another, with little or no external involvement
Public-Facing Documentation Public-facing documentation is a crucial part of any Open API ecosystem. The ability to search out answers (including error code documentation) to a product- or software-specific API without predefined access requirements enables potential integration partners to learn an API without engaging expensive and time-consuming resources, on both the publisher and subscriber side of the business. When appropriately architected, documentation can be created alongside (and potentially integrated with) the typical development process, saving time and resources. Public-facing documentation should include: •
Minimum required software for users (including third-party, if applicable)
•
Capabilities and usage guidance
•
Versioning information (if applicable)
•
Information regarding support, including contact information
•
Upgrade cadence
•
Well-defined error codes and conditions
•
UML and sample messages
•
Data schema and/or data dictionary
•
Clear distinctions between read only, writable fields
Standardized Terms, SLAs and Business Models Standardized terms, SLAs, and business models educate the community on common terms and business agreements, and reduce costs and demand for expensive resources. The following describes commonly available models and related terms, but are not prescriptive, nor a requirement for any business agreement.
RESTAURANT TECHNOLOGY NETWORK
|8|
Pricing and Business Model Transparency BUSINESS MODEL NAME/TYPE TERMS
SOFTWARE AS A SERVICE
TIERED TRANSACTION
NO COST/STRINGS ATTACHED SUPPORT-BASED
PERPETUAL LICENSE
Month to month, annual, or multi-year
Per transaction fee. May be N cents for X transactions and decrease based on total monthly or annual transactions. May be capped or convert to Software as a Service once a threshold is reached
One-time purchase of a license without transaction fees
May also be described as “freemium”. can convert to Software as a Service or Tiered Transaction license, based on multiple criteria. e.g. Number of Users, features etc.
Support may be included or an extra cost. Support may be subscription (OPEX) based, or per-incident based.
Support may be included or an extra cost. Support may be subscription (OPEX) based, or per-incident based.
Support may be included or an extra cost. Support may be subscription (OPEX) based, or perincident based.
Support may be included or an extra cost. Support may be subscription (OPEX) based, or per-incident based.
Should be included. May want to validate whether versions are automatically (Scope of maintenance upgraded, or can you should be spelled out in defer/manage upgrades contracts) on your schedule
Should be included. May want to validate whether versions are automatically upgraded, or can you defer/manage upgrades on your schedule
Typically subscribed to separately from license acquisition. May range between 10-25% of the perpetual license on an annual or monthly basis. May be mandatory or optional. perpetual license may include first n months/year(s)
Some features may be upgraded as part of a freemium subscription, others may only be upgraded as part of a Software as a Service subscription.
RESPONSIBILITIES
Hardware, hosting and system administration provided as part of subscription for webbased elements of solution. May require on-site hardware (e.g. POS), if so, that is generally at the customer’s expense. Deployment generally automated, may require some on-site management, which is usually at customer expense.
Hardware, hosting and system administration provided as part of subscription for webbased elements of solution. May require on-site hardware (e.g. POS), if so, that is generally at the customer’s expense. Deployment generally automated, may require some on-site management, which is usually at customer expense.
Typically all costs of hardware, hosting, system administration are all at the customer’s expense.
Hardware, hosting and system administration provided as part of subscription for webbased elements of solution. May require on-site hardware (e.g. POS), if so, that is generally at the customer’s expense. Deployment generally automated, may require some on-site management, which is usually at customer expense.
COST STRUCTURE
Monthly or yearly fees. Annual payments are usually lower than 12 monthly payments are usually lower than 12 monthly payments
Typically billed monthly in arrears, once the prior month’s transactions are tabulated.
One-time fee for perpetual license, and monthly/annual fees for support and maintenance. May negotiate payment terms to manage cash implications. Typically a CAPEX expense for perpetual license and OPEX for support and maintenance
No fees for “freemium” Monthly or yearly fees if converted to Software as a Service. Annual payments are usually lower than 12 monthly payments are usually lower than 12 monthly payments.
LEVEL OF SUPPORT (Suport equirements should be spell out in contracts) LEVEL OF SOFTWARE MAINTENANCE AND UPGRADES
|9|
RTN’S OPEN API FRAMEWORK
Testing & Sandbox Environments Testing and sandbox environments are vital for any company. This allows extensions, enhancements, and analysis without affecting a production environment. Many companies will have both internal corporate-facing, and external customer- or partner-facing sandbox environments that are independent copies of current or near-current software versions, including a basic amount of testing data. Key components of a modern testing environment include: •
If multiple versions of software are supported, include testing environments for each
•
1:1 functionality with current product systems
•
Example responses for integration messages
•
Example testing routines
•
Example test data
Validation and Certification Publishers and subscribers of APIs, regardless of business model or support, shall certify expected functionality is tested and validated for a particular integration. This will protect both the provider and the user of the API from misuse or mischaracterizations of functional capabilities, and ensure restauranteurs can be satisfied that a given integration has been tested successfully. Certified integrations will typically appear on both a subscribing company and publishing company’s website for transparency.
RESTAURANT TECHNOLOGY NETWORK
| 10 |
Extensibility, Enhancements, Flexibility & Updates Open APIs should be actively supported and extended throughout their lifecycle, up to and including end-of-life announcements. This includes a well documented product lifecycle for both internal corporate processes and external communications to partners and customers. A wellbuilt API goes through many of the following cycles: •
Create and test an API for functional requirements
•
Secure an API based on external and internal users
•
Manage & monitor an API for day-to-day functionality and operations
•
Appropriate versioning for new or non-backwards compatible functions
•
Continuously integrate feedback from customers and partners for new capabilities and versions
•
Proactively communicate to customers and partners when changes occur, what to expect, and how to respond
•
Well-defined and communicated maintenance windows and disaster scenarios
•
Internal, partner and customer-facing tools that allow access, configuration, and communication of important updates
Re-Use of Best Practice Data Models Best practice data models should be used across functionally-related APIs wherever possible, such as the RTN Menu Synchronization Software Integration Standard and related materials. RTN does not recommend a particular toolset or technology to achieve this, but rather a data model approach that enables code reuse across software. The practical outcome of best practice data model reuse ensures the same API uses the same format, attributes, elements and structure for similar objects, like a store or a menu.
| 11 |
RTN’S OPEN API FRAMEWORK
RTN Vision
Join Us
In an industry built on service and entrepreneurial spirit, purposebuilt technology fuels success. The Restaurant Technology Network aspires to help restaurant professionals and solution providers work together to solve problems large and small and inspire bold ideas for the future.
If you have a vested interest in the restaurant technology industry, join us. Collectively, our members shape the industry by creating and disseminating technology standards and technical guidance to benefit members. Through our cornerstone virtual think-tank workgroup meetings, our members solve industry challenges and prosper inside a unique, collaborative environment. + VIEW OUR MEMBERS
www.restauranttechnologynetwork.com RESTAURANT TECHNOLOGY NETWORK
| 12 |