Build an HTTP RTD service (legacy)

Note: This implementation supports signal enrichment only. Existing integrations remain supported, but no new capabilities will be added. Consider migrating to the gRPC integration.

This topic covers building an HTTP-based real-time data integration service.

Note: This topic applies to both partner-hosted and Index Cloud deployments. If you are deploying in Index Cloud, complete the generic sections below first, then follow the steps in Deploying in Index Cloud at the bottom of this topic. That section applies only to Index Cloud deployments.

Request format

Partners must expose an endpoint A URL which is configured to interact with a server in a specific way. accessible via HTTP POST. Index Exchange (Index) uses the following OpenRTB An open industry standard for communication between buyers and sellers of online advertising in real-time bidding auctions. It's published by the IAB. objects wherever possible:

Any ext extension objects in the objects listed above are not sent unless explicitly stated. Some bid request An OpenRTB request that is sent from a supply-side platform (SSP) or ad exchange to the DSP requesting a bid response for potential impressions. A bid request contains information about the impression that allows the DSP to decide whether to bid on the impression. attributes are removed or modified due to privacy requirements before being sent to you. See the Publisher request payload reference for details.

Sample app request

{
   "app": {
      "id": "12345", "name": "App Name", "bundle": "123456789",
      "domain": "appexample.com",
      "storeurl": "https://apps.apps.com/app/idexample",
      "cat": ["IAB9-7"], "ver": "4.56.0",
      "publisher": { "id": "555555", "name": "Publisher Name", "domain": "appexample.com" }
   },
   "device": {
      "connectiontype": 2, "devicetype": 4, "dnt": 0,
      "geo": { "city": "Cityville", "country": "USA", "lat": 11.11, "lon": -11.11, "region": "NY", "zip": "99999" },
      "ifa": "aaaaaaaa-ebad-aaaa-aaaa-aaaaaaa", "ip": "123.45.6.789",
      "language": "en", "lmt": 0, "make": "Phonester", "model": "Phone",
      "os": "Android", "osv": "9"
   },
   "imp": [{
      "id": "1", "tagid": "12345_12345",
      "banner": { "w": 728, "h": 90, "pos": 1, "gpid": "/1234567/home/mpu/atf" }
   }],
   "user": {
      "id": "AbcdEfgHijklmnoP",
      "eids": [{ "source": "ID_Provider.com", "uids": [{ "id": "Abcdefgh1234567..." }] }]
   },
   "regs": { "coppa": 0, "gdpr": 0, "us_privacy": "1---" }
}

Sample web request

{
   "site": {
      "id": "12345", "page": "https://example.com/section/", "domain": "example.com",
      "publisher": { "id": "555555", "domain": "example.com", "name": "Publisher Name" },
      "content": { "url": "https://example.com/content-link/" }
   },
   "device": {
      "connectiontype": 2, "devicetype": 2, "dnt": 0,
      "geo": { "city": "Cityville", "country": "USA", "lat": 11.11, "lon": -11.11, "region": "NY" },
      "ip": "2001:db8::1234", "language": "en", "os": "Windows"
   },
   "imp": [{ "id": "1", "tagid": "12345_12345", "banner": { "w": 728, "h": 90, "pos": 1 }, "secure": 1, "ext": { "gpid": "/1234567/home/mpu/atf" } }],
   "user": { "id": "AbcdEfgHijklmnoP", "eids": [{ "source": "ID_Provider.com", "uids": [{ "id": "Abcdefgh1234567..." }] }] },
   "regs": { "ext": { "gdpr": 0 } }
}

Sample streaming TV request

{
   "app": {
      "id": "885120", "name": "Show TV", "bundle": "MYBUNDLE",
      "storeurl": "https://www.show.com/theshow",
      "publisher": { "id": "1234567", "name": "Publisher Name" },
      "content": { "cat": ["IAB1"], "title": "The Show", "genre": "entertainment", "language": "en", "len": 3600, "livestream": 1 }
   },
   "imp": [{
      "id": "1", "bidfloor": 8,
      "video": { "w": 1920, "h": 1080, "placement": 1, "plcmt": 1, "mimes": ["video/mp4"], "minduration": 5, "maxduration": 60 }
   }],
   "user": { "id": "aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaa" },
   "regs": { "coppa": 0, "ext": { "us_privacy": "1YNN" } }
}

Response format

The HTTP response should be in JSON format using the following structure:

{ "segment_ids": ["cat_owners", "target_shoppers", "gender_female"] }

Response codes and circuit breaker logic

A 2xx HTTP response code should be returned for successful responses.

If Index receives a 4xx or 5xx error, or more than 3% of requests have exceeded a 30ms timeout, Index's circuit breaker triggers and requests to your container are throttled. Requests that time out also trigger this logic. When error rates return to nominal levels, circuit breakers reopen and regular traffic resumes automatically.

Note: The circuit breaker uses a 30ms internal timeout for both HTTP and gRPC integrations. The 5ms figure is the SLA for your response to be used in auction processing; the 30ms figure is the outer timeout after which Index treats the request as failed for circuit breaker purposes.

To send test traffic to your container and validate it against a live-like environment before deployment, see Using the Index testing tool. The testing tool described there supports HTTP integrations as well as gRPC.

Response examples

In the following example, the partner returns segment data:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "segment_ids": ["sports_news", "football_players"] }

In the following example, the partner has no data yet. An empty response is also acceptable:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "segment_ids": [] }

Authentication

If you require authentication, Index supports OAuth, tokens in the query string, or a token in the request header. Index can also provide IP ranges for allowlisting, though these may change over time and require regular updates.

Deploying in Index Cloud

Note: HTTP support in Index Cloud exists for existing integrations only. No new capabilities will be added to the HTTP model. Consider migrating to the gRPC integration.

The following requirements apply if you are deploying your HTTP container in Index Cloud. If you are hosting the service yourself, skip this section.

Endpoint requirements

Containers must expose all endpoints via HTTP or HTTPS on the SERVER_PORT environment variable. See the Environment variables section in Building a Docker container.

The required metrics endpoint metric is http.server.request.duration, a histogram with boundaries 0.0025, 0.005, 0.01, 0.025, and 0.05 in seconds. Total cardinality must not exceed 10,000.

Resource requirements

Containers should handle 100,000 QPS Queries Per Second (QPS). The number of bid requests a DSP processes per second. Also known as impressions per second. using 10 CPU cores and 10 GB RAM. Images must not exceed 1 GiB.

Deployment and rollout

Index deploys via Helm and Argo CD into a dedicated Kubernetes namespace using a staged rollout strategy. A small set of instances launches first with real traffic. If your container performs within the 5ms SLA with an error rate below 3%, all instances roll over. Otherwise, the deployment is automatically rolled back.

Security

All containers are scanned by Sonatype Vulnerability Scanner on download and on an ongoing basis. For details on CVSS scoring thresholds and base image recommendations, see Building a Docker container. In addition, containers are:

• Deployed with a read-only filesystem, and not permitted to run as root.

• Restricted from egress outside of Index Cloud. All startup data must be included in the container or mounted via config file.

Next: If you are deploying in Index Cloud, continue to Building a Docker container to package your container, then validate it with Using the Index testing tool. If you are hosting the service yourself, validate your implementation with Using the Index testing tool; your container is ready to deploy to your own infrastructure once it passes.