To effectively integrate ROOK into your solution, it's crucial to establish a robust architecture that supports receiving, storing, and serving health data. This article outlines the recommended architecture for ROOK clients, ensuring a smooth and efficient data management process.
Core Components of the Recommended Architecture
Data Reception:
You'll need to create an endpoint, such as a webhook URL, in your backend to receive data from ROOK.
ROOK delivers data primarily via webhooks for real-time updates and daily summaries.
Data Webhooks deliver health data (e.g., events and summaries) in real time, covering Sleep, Physical, and Body health pillars.
Notification Webhooks provide updates about integration-specific actions, such as user creation or deletion, and data source connections or disconnections, this is an add-on that you can review more about here.
Ensure your endpoint can accept HTTP POST requests and process incoming JSON payloads.
Data Storage:
Store the data received from ROOK in your own system or cloud infrastructure.
This ensures you can manage, process, and analyze the data as needed for your specific use case.
The ROOK API is not designed to serve as a backend or storage system. You should not make API requests whenever users access their data, but instead, query your own database.
Backend Development:
Your backend will be responsible for receiving and storing data from ROOK.
It will also be responsible for processing the data as needed and serving that data to your end-user applications.
Your backend should also handle the retry logic for failed webhook deliveries: 1 hour, 24 hours, and 48 hours.
Frontend or Application Integration:
If you have a mobile app:
You can integrate ROOK’s SDKs to extract data from mobile-based sources (e.g., Apple Health, Health Connect).
Alternatively, you can use the ROOK Extraction App, a ready-to-use solution for mobile-based data sources.
If you have a web app:
Your backend should serve the stored data to the web app, allowing you to display health metrics or provide actionable insights.
You should build a connections web page or app view using ROOK APIs to connect users to their health data sources.
Detailed Breakdown of Data Flow
User Connects Data Source: The user authorizes ROOK to access their health data through your app or web interface.
For API-based data sources, use the ROOK Connections Page for sandbox testing, and the /authorizer endpoint for production.
For mobile-based data sources, use the ROOK Extraction App or integrate ROOK SDKs.
ROOK Extracts Data: ROOK collects data from the user's data source via APIs, SDKs, or the ROOK Extraction App.
ROOK extracts pre-existing data up to 7 days for API-based sources and 29 days for mobile-based sources.
ROOK Processes Data: The extracted data is harmonized, standardized, cleaned, and normalized to ensure consistency and quality.
Data is organized into three core pillars: Physical Health, Body Health, and Sleep Health.
Data is delivered as daily summaries or specific events, formatted using standardized JSON schemas.
ROOK Delivers Data:
ROOK delivers data in real-time through Data Webhooks, covering Sleep, Physical, and Body health data.
You can use the ROOK API for specific, on-demand queries or additional data flexibility.
Your Backend Receives Data:
Your backend endpoint receives the data from ROOK via webhooks.
The webhook must respond with a 200 OK, 201 Created, or 202 Accepted status code to acknowledge receipt. Invalid responses trigger retry attempts.
If delivery fails, data is stored in buckets for client retrieval, 3 days for sandbox and 10 days for production.
Your Backend Stores Data:
Your backend stores the received data in a database.
Your Application Serves Data:
Your front-end application requests data from your backend and displays it to the user.
Key Considerations for ROOK Clients
Webhooks for Real-Time Updates: Webhooks are the preferred method for receiving real-time data updates from ROOK, eliminating the need for constant polling.
API for On-Demand Queries: Use the ROOK API for specific data retrieval needs, but remember it is not a substitute for a robust backend.
Security: Use the X-ROOK-HASH header for HMAC validation to ensure data authenticity.
Data Validation: Validate the data structure and content to ensure accurate data handling.
Separate Environments: Set up separate configurations for sandbox and production environments to ensure stability.
Data Duplication: Implement logic to handle duplicate data sent from ROOK based on the document_version field.
By implementing this recommended architecture, you can efficiently leverage the power of ROOK to integrate and manage health data effectively.