How revealbot/panda works
Main Components
• Client Interface (Panda::Client): This is the primary class that a user instantiates with an access token. It is the entry point for performing any API call (e.g., retrieving advertisers, campaigns, ad groups, ads, reports, etc.).
• Configuration Module (Panda::Configuration): This handles the gem’s configuration settings (API keys, base URLs, API versions). Its role is to provide a globally accessible configuration via a dedicated configure block.
• HTTP Communication (Panda::HTTP_Request and Panda::HTTP_Response): These modules manage the actual sending of HTTP requests and processing of responses from the TikTok Ads API.
• Error Handling (Panda::Error_Middleware and specific custom errors from Panda::Errors): These handle exceptions and problem states. The custom exceptions like APIError, NoPermissionsError, NotAuthorizedError, and TooManyRequestsError are used to signal and handle different error conditions.
• Data Structures (such as Panda::Collection and Panda::Item): These components could assist in mapping and manipulating collections of advertiser details, campaigns, etc.
Relationships and Interactions
• The client (Panda::Client) acts as a façade that ties various components together. When a method such as client.advertisers is invoked, the client uses configuration details, builds an HTTP request, and sends it.
• The HTTP_Request component packages the necessary request details (URL, headers, parameters) using configuration.
• The HTTP_Response component processes the raw response and routes it either as valid data or passes errors to the error handling middleware.
• The Error Middleware catches error responses and then raises appropriate custom exceptions.
• Additionally, utility components for handling collections or individual items help parse and structure the results coming back from the API.
Additional Architectural and Design Insights
• The gem follows a modular design where different responsibilities (client operations, configuration, HTTP communication, and error management) are separated.
• The configuration design pattern (configuration block) centralizes API key management and endpoint details.
• The error handling design is robust, with distinct classes for various API issues ensuring clarity for client applications that use the gem.
• The tests (in the spec/ directory) have been set up to ensure each of these components works as expected, which reinforces a clean separation of concerns.