The following are guidelines for designing a reporting API, based on Funnel’s experience from integrating a large number of advertising platforms. Please note that they are guidelines and not strict requirements for Funnel to integrate ads reporting data.
Technical preferences
- REST, or another simple HTTP protocol for requesting data.
- HTTPS for secure transport
- Appropriate HTTPS status codes for “not found”, “forbidden”, “internal error” etc
- An “access token” unique for each customer/account to secure data access
- JSON formatted data for metadata and statistics
Data considerations
- Account metadata endpoint returning Account ID, Account Name or similar. Including Created Date, Permission Level and Timezone also improves the end user experience.
- Endpoint for listing account or user specific entities (eg. custom dimensions and metrics)
- Reporting endpoint that delivers statistics per day
- Parameters to select dimensions to group on (e.g campaign, site, category)
- Parameters to select metrics
- Parameters to select date range
- Expose currency on appropriate level (customer/ad account, or campaign if currency can vary by campaign)
Other requests
- API credentials easily accessible to the customer from GUI
- Simple documentation of endpoints and expected data format
- Documentation of quotas and data stability (how far back data has to be reloaded to ensure full accuracy)
- Technical support contact info