API Overview

Ring DAS provides comprehensive APIs to programmatically manage campaigns, deliver ads, track user activity, and analyze performance. This guide introduces the available APIs and helps you choose the right one for your use case.

Available APIs

Ring DAS offers two primary API types:

1. Management API (GraphQL)

The Management API is a GraphQL-based API that provides complete control over Ring DAS platform configuration and campaign management.

Base URL: https://api.ringdas.com/graphql

Use Cases:

• Campaign management (Deals, Line Items, Creatives)
• Inventory configuration (Ad Units, Placements, Key-Values)
• Audience segment management
• Offer and catalog operations
• Report generation and data export
• Network configuration and settings

Key Features:

• Single endpoint for all operations
• Flexible queries - request exactly the data you need
• Strong typing with schema introspection
• Mutations for creating, updating, and deleting resources
• Real-time subscriptions (where supported)
• Batch operations for efficiency

Best For:

• Building custom campaign management tools
• Automating campaign operations
• Integrating with CRM or marketing automation systems
• Creating custom reporting dashboards
• Platform administration and configuration

2. Delivery APIs (REST)

The Delivery APIs are high-performance REST endpoints optimized for real-time ad serving and tracking.

Key APIs:

Ad Request API

Base URL: https://delivery.ringdas.com/api/v1/ads

Retrieves ads for display on your website or application.

Use Cases:

• Requesting ads for ad units
• Server-side ad rendering
• Native ad integration
• Mobile app ad delivery

Activity Pixel API

Base URL: https://pixel.ringdas.com/api/v1/events

Tracks user activity and eCommerce events for targeting and attribution.

Use Cases:

• eCommerce tracking (product views, cart actions, purchases)
• Custom event tracking
• Conversion attribution
• Audience segmentation data

Click Tracker API

Base URL: https://delivery.ringdas.com/api/v1/clicks

Records ad clicks and manages redirects.

Use Cases:

• Click tracking
• Click-through attribution
• Deep linking

Best For:

• Real-time ad serving
• High-throughput event tracking
• Mobile and server-side integrations
• Low-latency requirements

GraphQL vs REST: When to Use Each

Rule of Thumb:

• Use GraphQL Management API for anything related to configuration, campaign management, or reporting
• Use REST Delivery APIs for real-time ad serving, tracking, and high-throughput operations

API Architecture Overview

graph TB
    subgraph "Client Applications"
        A[Campaign Management Tool]
        B[Website/Mobile App]
        C[Analytics Dashboard]
    end

    subgraph "Ring DAS APIs"
        D[Management API<br/>GraphQL]
        E[Ad Request API<br/>REST]
        F[Activity Pixel API<br/>REST]
        G[Click Tracker API<br/>REST]
    end

    subgraph "Ring DAS Platform"
        H[DELIVERY Module]
        I[INVENTORY Module]
        J[AUDIENCE Module]
        K[OFFERS Module]
        L[REPORTS Module]
        M[DAS PIXEL Module]
    end

    A -->|GraphQL Queries/Mutations| D
    B -->|Ad Requests| E
    B -->|Event Tracking| F
    B -->|Click Tracking| G
    C -->|Report Queries| D

    D --> H & I & J & K & L
    E --> H
    F --> M
    G --> H
    M --> J

    style D fill:#4CAF50
    style E fill:#2196F3
    style F fill:#FF9800
    style G fill:#9C27B0

Getting Started with Ring DAS APIs

Follow these steps to start using Ring DAS APIs:

Step 1: Obtain API Credentials

1. Log in to your Ring DAS instance
2. Navigate to Settings > API Keys
3. Click Generate New Key
4. Provide a descriptive name (e.g., "Production Campaign Tool")
5. Copy and securely store your API key

Security Best Practice: Never commit API keys to version control. Use environment variables or secure credential management systems.

Step 2: Set Up Authentication

All Ring DAS API requests require authentication using a Bearer token:

Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for detailed examples in multiple programming languages.

Step 3: Make Your First API Call

GraphQL Management API Example

curl -X POST https://api.ringdas.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { network(id: \"YOUR_NETWORK_ID\") { id name status } }"
  }'

Ad Request API Example

curl -X POST https://delivery.ringdas.com/api/v1/ads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "YOUR_NETWORK_ID",
    "adUnit": "homepage-banner",
    "count": 1
  }'

Step 4: Explore the API Documentation

• Management API (GraphQL): Management API Overview
• Delivery APIs: Ad Request API | Activity Pixel API
• Code Examples: SDK Overview

Step 5: Understand Rate Limits

Ring DAS enforces rate limits to ensure system stability. Review the Rate Limits & Quotas guide to understand:

• Default limits per API
• How to monitor your usage
• Requesting limit increases
• Best practices for staying within limits

API Capabilities by Module

Ring DAS APIs provide access to all platform modules:

DELIVERY Module

GraphQL Endpoints:

• Campaign CRUD: deals, lineItems, creatives
• Campaign lifecycle: activateLineItem, pauseLineItem, archiveDeal
• Bulk operations: bulkCreateLineItems, bulkUpdateCreatives

REST Endpoints:

• Ad requests: POST /api/v1/ads
• Click tracking: GET /api/v1/clicks/{clickId}

INVENTORY Module

GraphQL Endpoints:

• Inventory management: adUnits, placements, tags
• Targeting configuration: keyValues, keyValueOptions
• Floor pricing: floorPrices, updateFloorPrice

AUDIENCE Module

GraphQL Endpoints:

• Segment management: segments, createSegment, updateSegment
• Audience data: audienceDatabases, segmentSize
• User features: userFeatureStore

OFFERS Module

GraphQL Endpoints:

• Catalog management: catalogs, products, offers
• Schema operations: schemas, defineSchema
• Sync operations: syncCatalog, updateProducts

DAS PIXEL Module

REST Endpoints:

• Event tracking: POST /api/v1/events
• Session management: JavaScript SDK (dlApi.init())
• User identification: JavaScript SDK (dlApi.setUserId())

REPORTS Module

GraphQL Endpoints:

• Query execution: executeQuery, savedQueries
• Report generation: generateReport, scheduleReport
• Data export: exportData

SETTINGS Module

GraphQL Endpoints:

• Network configuration: network, updateNetwork
• Feature flags: featureFlags, toggleFeature
• User management: users, permissions

Interactive API Playground

Ring DAS provides an interactive GraphQL playground where you can:

• Explore the complete API schema
• Test queries and mutations in real-time
• View auto-generated documentation
• Copy working code examples

Access the Playground:

• URL: https://api.ringdas.com/graphql/playground
• Authentication: Use your API key in the HTTP headers panel

Tip: The GraphQL playground includes schema introspection. Press Ctrl+Space to see available fields and operations at any cursor position.

API Versioning

Ring DAS APIs follow semantic versioning:

• Current Version: v1
• Stable: All v1 endpoints are considered stable
• Deprecation Policy: 12 months notice before any breaking changes
• Beta Features: Marked with @beta directive in GraphQL schema

Version in URLs:

• GraphQL: Version embedded in endpoint (/graphql)
• REST: Version in path (/api/v1/...)

Breaking changes will result in a new major version (e.g., v2), allowing you to migrate at your own pace.

Common Use Cases

Campaign Automation

Automate campaign creation and management:

1. Use GraphQL to create deals, line items, and upload creatives
2. Configure targeting and budget parameters
3. Activate campaigns programmatically
4. Monitor performance via Reports API

Example: Creating an Advertising Campaign

Real-Time Ad Serving

Integrate ad delivery into your website or app:

1. Implement Ad Request API for server-side rendering
2. Or use JavaScript SDK for client-side requests
3. Implement Activity Pixel for conversion tracking
4. Use Click Tracker for attribution

Example: Ad Request Integration

Custom Reporting Dashboard

Build custom analytics and reporting:

1. Use GraphQL to query campaign performance
2. Execute saved queries or ad-hoc queries
3. Export data for external analysis
4. Schedule automated reports

Example: Generating Reports

Retail Media Integration

Enable product catalog-based advertising:

1. Use Offers API to sync product catalogs
2. Configure product schemas via GraphQL
3. Create dynamic line items with product targeting
4. Track conversions via Activity Pixel API

Example: Product Catalog Sync

API Best Practices

1. Use API Keys Securely

• Store API keys in environment variables
• Rotate keys regularly (every 90 days recommended)
• Use different keys for development and production
• Revoke unused keys immediately

2. Handle Rate Limits Gracefully

• Implement exponential backoff for rate limit errors
• Monitor your usage via API or dashboard
• Cache responses when possible
• Use bulk operations to reduce request count

3. Optimize GraphQL Queries

• Request only the fields you need
• Use query fragments for reusable field sets
• Leverage aliases for multiple queries in one request
• Paginate large result sets

4. Implement Error Handling

• Check HTTP status codes
• Parse GraphQL error messages
• Log errors for debugging
• Implement retry logic for transient failures

5. Monitor API Performance

• Track API response times
• Set up alerts for errors or slow responses
• Use tracing IDs for debugging
• Review API usage reports regularly

Next Steps

Now that you understand Ring DAS APIs, proceed with:

1. Authentication Setup - Configure API key authentication
2. Management API Overview - Learn GraphQL operations
3. Campaign Operations - Create and manage campaigns via API
4. Rate Limits & Quotas - Understand system limits
5. SDK Overview - Use client libraries for easier integration

Support & Resources

• API Reference: Complete endpoint documentation in this section
• Code Examples: GitHub Repository
• Community: Developer Forum
• Support: Contact your account manager or support team

Related Topics

• Authentication Guide - API key management and security
• Rate Limits & Quotas - System limits and monitoring
• Error Handling - Error codes and troubleshooting
• SDK Overview - Client libraries and tools