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