diff --git a/Concurrent-Streams.md b/Concurrent-Streams.md index e8c555d..a760780 100644 --- a/Concurrent-Streams.md +++ b/Concurrent-Streams.md @@ -26,7 +26,16 @@ THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MAT - [Implementation Guidance](#impguide) - [General Information](#geninfo) - [Content Information](#contentinfo) - - [json Examples](#json) + - [Base URI](#base-uri) + - [Endpoints](#endpoints) + - [Query Parameters](#query-parameters) + - [Path Parameters](#path-parameters) + - [Request Examples](#request-examples) + - [Response Examples](#response-examples) + - [Usage Guidance](#usage-guidance) + - [Role-Based Access](#role-based-access) + - [Integration with Event Forecasts API](#integration) + # Introduction This is version 1.0 of the Concurrent Streams specification and every attempt will be made to make future versions backward compatible if possible. @@ -120,10 +129,123 @@ A provider can sufficiently identify a specific live event with one or more of t It is strongly recommended that some identifier for the content in question is passed. This could correspond to the content owners Content Management System (CMS), and/or some other commercially available content identifier. Whatever content ID is provided, should be the same as the ID that is provided on the Bid Request. Additional information about the Content can be provided in the Extended Content IDs array. +## Base URI + +``` +https://api.example.com/v1/concurrentstreams + +``` + +---------- + +## Endpoints + +### Collection Endpoints + +**`GET /concurrentstreams`** + +- Retrieves current concurrent stream data for all active live events +- Returns near real-time viewership signals +- Supports filtering by requestor and Streams Data Provider (SDP) + +**`GET /concurrentstreams/{contentId}`** + +- Retrieves concurrent stream data for specific content +- Returns detailed viewership breakdown by stream type and region +- Includes SSAI and CSAI stream counts + +---------- + +## Query Parameters + +### Filtering Parameters + +#### Table + +| Parameter | Type | Description | +|-----------|------|-------------| +| `requestor` | String | Identifies the requesting entity (SSAI, publisher, DSP, advertiser) | +| `sdp` | String | Optional Streams Data Provider identifier for multi-provider scenarios | +| `region` | Integer | Filters stream data by region code (1=N_America_East, 2=N_America_West, 3=Europe, etc.) | + +### Pagination Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `limit` | Integer | Maximum results per page (default: 50, max: 100) | +| `offset` | Integer | Starting position (default: 0) | + +---------- + +## Path Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `{contentId}` | String | Unique content identifier (CMS ID or persistent identifier) | + +---------- -## json Examples +## Request Examples +### Get All Concurrent Streams + +```http +GET /v1/concurrentstreams?requestor=example-ssai +Authorization: Bearer {access_token} +``` + +### Get Concurrent Streams for Specific Content + +```http +GET /v1/concurrentstreams/CMS123?requestor=example-ssai +Authorization: Bearer {access_token} +``` + +### Filter by Region + +```http +GET /v1/concurrentstreams?requestor=example-ssai®ion=1 +Authorization: Bearer {access_token} ``` + +---------- +## Response Examples + +### Single Content Response + +```json +{ + "version": "1.0.0", + "timestamp": "1738785540000", + "streamsdata": [ + { + "sdp": "TV Network A", + "mediastreams": [ + { + "content": { + "id": "CMS123", + "genres": [646], + "gtax": 9, + "contentrating": "PG-13", + "channel": {"name": "Comedy Channel"} + }, + "eventstart": "1738785000000", + "eventend": "1738796800000", + "streamcount": [ + {"region": 1, "sstreams": 140000, "cstreams": 400000}, + {"region": 2, "sstreams": 100000, "cstreams": 20000}, + {"region": 3, "sstreams": 500000, "cstreams": 10000} + ] + } + ] + } + ] +} +``` + +### Multi-Event Response + +```json { "version": "1.0.0", "timestamp": "1713366138", @@ -221,3 +343,100 @@ It is strongly recommended that some identifier for the content in question is p ] } ``` +---------- + +## Usage Guidance + +### Data Freshness + +- API provides **near real-time** viewership data +- Typical latency: 30-60 seconds from actual viewership +- Subscribers should poll at appropriate intervals (recommended: 1-5 minutes) +- Avoid excessive polling to respect rate limits + +### Content Identification + +- Use **CMS IDs** or other persistent identifiers for content +- Content identifiers should remain consistent across API calls +- Map content IDs to internal systems for correlation +- Content ID should match the ID provided in bid requests + +### Viewership Values + +- Stream counts represent users at the **live edge** +- Excludes DVR/time-shifted viewing +- Counts are point-in-time snapshots, not cumulative +- Regional breakdowns enable geographic scaling decisions + +### Region Codes + +- Region codes are integers representing geographic areas +- Example codes: 1=N_America_East, 2=N_America_West, 3=Europe +- Coarse granularity acceptable for MVP +- Drives system scaling in regional datacenters + + +### Scaling Recommendations + +**Infrastructure Scaling:** + +- Monitor stream count trends (increasing/decreasing) +- Scale proactively when counts exceed 80% of capacity +- Implement auto-scaling based on stream count thresholds + +**Bidding Strategy:** + +- Higher viewership = higher competition = adjust bids accordingly +- Use historical patterns to predict viewership curves + +**QPS Management:** + +- Calculate expected QPS: (concurrent streams × ad requests per stream) +- Scale ad serving infrastructure before reaching capacity +- Implement circuit breakers for overload protection + +---------- + +## Role-Based Access + +**SSAI Provider (Read Access)** + +- Read concurrent stream data +- Query by content and region +- Monitor viewership for infrastructure scaling + +**Publisher (Read Access)** + +- Read concurrent stream data for owned content +- Monitor viewership for monetization optimization +- Access historical viewership patterns + +**DSP/Advertiser (Read Access)** + +- Read concurrent stream data +- Adjust bidding strategies based on viewership +- Optimize campaign pacing + +**Streams Data Provider (Write + Read Access)** + +- Publish concurrent stream data (if applicable) +- Read all stream data +- Manage data quality and accuracy + +---------- + +## Integration with Event Forecasts API + +The Concurrent Streams API complements the Event Forecasts API (upcoming): + +**Event Forecasts API** - Provides advance notice of upcoming events with forecasted viewership + +**Concurrent Streams API** - Provides real-time viewership during live events + +**Recommended Integration Pattern:** + +1. Use Event Forecasts API to prepare infrastructure for upcoming events +2. Switch to Concurrent Streams API once event goes live +3. Compare actual viewership (Concurrent Streams) vs. forecast (Event Forecasts) for accuracy tuning +4. Use historical concurrent stream data to improve future forecasts + diff --git a/implementation.md b/implementation.md new file mode 100644 index 0000000..d07fd34 --- /dev/null +++ b/implementation.md @@ -0,0 +1,351 @@ +# API Conventions Reference + + + +## Table of Contents +- [Overview](#overview) +- [Naming Conventions](#naming-conventions) +- [HTTP Methods](#http-methods) +- [Authentication](#authentication) +- [Request and Response Formats](#request-response-formats) +- [Status Codes](#status-codes) +- [Error Handling](#error-handling) +- [Pagination](#pagination) +- [Versioning](#versioning) +- [Rate Limiting](#rate-limiting) +- [Sorting](#sorting) + + +---------- + + + +## Overview + +This document establishes common conventions and standards applicable to all APIs. API-specific details (endpoints, query parameters, examples) are documented in separate API specification files. + +---------- + + + +## Naming Conventions + +Establishes foundational naming rules for resources, fields, and parameters across all APIs. + +**Resource Naming** + +- Use plural nouns for collections (e.g., `/eventforecasts`, `/concurrentstreams`) +- Use lowercase for resource paths +- Avoid verbs in resource names (actions expressed through HTTP methods) + +**Field Naming** + +- Use camelCase for JSON fields (e.g., `eventId`, `contentId`, `expectedPeak`) +- Use lowercase for query parameters (e.g., `scheduledstart`, `scheduledend`, `lastmodifieddate`) +- Boolean fields use `is`, `has`, or descriptive names (e.g., `tentative`, `unplanned`) + +---------- + + + +## HTTP Methods + +Defines how HTTP verbs map to operations on API resources. + +**GET** - Retrieve resources (idempotent, safe) + +- Collection: `GET /resources` with filtering/sorting/pagination +- Individual: `GET /resources/{id}` + +**POST** - Create resources (non-idempotent) + +- Returns 201 Created with Location header pointing to new resource + +**PUT** - Replace entire resource (idempotent) + +- Returns 200 OK or 204 No Content + +**PATCH** - Partial update (idempotent) + +- Modifies specified fields only + +**DELETE** - Remove resource (idempotent) + +- Returns 204 No Content + +---------- + + + +## Authentication + +Specifies security mechanisms for API access and authorization. + +Authentication protocol is left to the discretion of the event creator, and should be discussed with API users a priori. The suggested protocol to utilize is OAuth 2.0 for secure communication. Include the access token in the Authorization header: Authorization: Bearer {token}. + +**Mechanism:** OAuth 2.0 (Client Credentials or Authorization Code grant) + +**Required Headers:** + +``` +Authorization: Bearer {access_token} +Content-Type: application/json +Accept: application/json + +``` + +**Optional Headers:** + +``` +Idempotency-Key: {uuid} +X-Request-ID: {uuid} + +``` + +**Security Requirements:** + +- HTTPS only (TLS 1.2+) +- Token expiration: 1 hour (access), 30 days (refresh) +- Role-based access control as defined per API + +**Error Responses:** + +- `401 Unauthorized` - Missing/invalid credentials +- `403 Forbidden` - Insufficient permissions + +---------- + + + +## Request and Response Formats + +Defines data structure, encoding, and format conventions for API communication. + +**Content Type:** `application/json; charset=utf-8` + +**Date/Time Format:** ISO 8601 UTC (`YYYY-MM-DDTHH:MM:SSZ`) + +**Field Conventions:** + +- camelCase for JSON fields +- Optional fields may be omitted +- `null` indicates explicit removal (PATCH operations) +- Omitted fields in PATCH are not modified + +**Response Headers:** + +``` +Content-Type: application/json; charset=utf-8 +X-Request-ID: {uuid} +X-RateLimit-Limit: {number} +X-RateLimit-Remaining: {number} +X-RateLimit-Reset: {timestamp} + +``` + +**Collection Response Structure:** + +json + +```json +{ + "data": [ ... ], + "pagination": { + "limit": 50, + "offset": 0, + "total": 1234, + "hasMore": true + } +} +``` + +---------- + + + +## Status Codes + +Follow standard HTTP status codes per RFC 7231. + +**Success (2xx):** + +- `200 OK` - Successful GET, PUT, PATCH +- `201 Created` - Successful POST with Location header +- `204 No Content` - Successful DELETE + +**Client Errors (4xx):** + +- `400 Bad Request` - Invalid JSON or missing required fields +- `401 Unauthorized` - Missing/invalid authentication +- `403 Forbidden` - Insufficient permissions +- `404 Not Found` - Resource does not exist +- `409 Conflict` - Duplicate resource identifier +- `422 Unprocessable Entity` - Invalid field values +- `429 Too Many Requests` - Rate limit exceeded + +**Server Errors (5xx):** + +- `500 Internal Server Error` - Unexpected error +- `503 Service Unavailable` - Temporary outage + +---------- + + + +## Error Handling + +Defines standardized error response structure and common error codes. + +**Standard Error Response:** + +json + +```json +{ + "error": { + "code": "string", + "message": "string", + "details": [ + { + "field": "string", + "issue": "string" + } + ], + "requestId": "string" + } +} +``` + +**Common Error Codes:** + +- `INVALID_JSON`, `MISSING_REQUIRED_FIELD`, `INVALID_FIELD_VALUE`, `INVALID_DATE_FORMAT` (400) +- `MISSING_CREDENTIALS`, `INVALID_TOKEN`, `EXPIRED_TOKEN` (401) +- `INSUFFICIENT_PERMISSIONS` (403) +- `RESOURCE_NOT_FOUND` (404) +- `DUPLICATE_RESOURCE`, `RESOURCE_CONFLICT` (409) +- `RATE_LIMIT_EXCEEDED` (429) +- `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE` (500/503) + +**Best Practices:** + +- Include X-Request-ID for tracing +- Provide actionable error messages +- Include field-level details for validation errors +- Never expose internal system details + +---------- + + + +## Pagination + +Defines standard approach for handling large result sets. + +**Query Parameters:** + +- `limit={number}` - Maximum results per page (default: 50, max: 100) +- `offset={number}` - Starting position (default: 0) + +**Response Structure:** + +json + +```json +{ + "data": [ ... ], + "pagination": { + "limit": 50, + "offset": 0, + "total": 1234, + "hasMore": true + } +} +``` + +**Pagination Fields:** + +- `limit` - Number of results in current page +- `offset` - Starting position of current page +- `total` - Total resources matching query +- `hasMore` - Boolean indicating more results exist + +---------- + + + +## Versioning + +Defines API evolution and backward compatibility strategy. + +**Strategy:** URI-based versioning with major version in base path (e.g., `/v1/`, `/v2/`) + +**Version Policy:** + +- Major version only (v1, v2) +- Increment for breaking changes (field removal, type changes, behavior changes) +- Maintain backward compatibility within same major version +- Support previous versions for 12 months minimum +- Provide 6-month deprecation notice + +---------- + + + +## Rate Limiting + +Defines request throttling policies to protect API resources and ensure fair usage. + +**Default Thresholds:** + +- 1,000 requests/hour per client +- 100 requests/minute burst limit + +**Response Headers:** + +``` +X-RateLimit-Limit: {number} +X-RateLimit-Remaining: {number} +X-RateLimit-Reset: {timestamp} + +``` + +**429 Response:** + +json + +```json +{ + "error": { + "code": "RATE_LIMIT_EXCEEDED", + "message": "Rate limit exceeded. Retry after {seconds} seconds.", + "requestId": "..." + } +} +``` + +Includes `Retry-After: {seconds}` header. + +**Best Practices:** + +- Monitor X-RateLimit-Remaining header +- Implement exponential backoff for 429 responses +- Cache responses to reduce API calls + +---------- + + + +## Sorting + +Defines standard approach for ordering result sets. + +**Query Parameters:** + +- `sort={field}` - Field to sort by +- `order=asc|desc` - Sort direction (default: asc) + +**Example:** + +``` +GET /resources?sort=createdDate&order=desc +```