Cached API integration method

This method requires that you integrate with Index by registering your segment taxonomy on our platform and you connect to Index using an HTTP GET endpoint A URL which is configured to interact with a server in a specific way.. After the integration is complete, Index begins storing your responses in a cached location. When Index receives an ad request, we check the cached data against specific 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. attributes sent in the incoming request (for example, page URL, appbundle ID). If we find segments that match the attributes before a specified timeout, they are added to the request and any matching deals get activated and are then sent to DSPs. If we don't find any relevant segments, Index makes an asynchronous call to your endpoint with OpenRTB attributes in the request. If we receive a response with updated segment data before a specified timeout, we write the updated data to the cache so it can be used in a future request.

Request formats

Partners using a Cached API integration must expose a endpoint accessible through an HTTP GET request, where Index can embed the keys to enrich against (for example, URL, app bundle, IP, etc) in the URL as URL-encoded query string parameters.

Index will only ever populate one key in the URL in an HTTP request to avoid needing to account for complex-cache keys. For partners providing enrichment against multiple keys, considerations for complex keys can be discussed. Index can also provide additional keys in the HTTP request if useful in decisioning logic, but the cache will be stored against the primary key.

Example

Using an example endpoint of https://www.mypartner.com/segments?url={URL_MACRO}, if an incoming ad request includes the apple.com/developer/news/iphone URL, Index would make the following call to your endpoint:

GET https://www.mypartner.com/segments?url=apple.com%2Fdeveloper%2Fnews%2Fiphone

Response format

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

Object	Required?	Description	Format
segment_ids	Required	The list of segments that are activated. Note: If there are no results, respond with an empty segment_ids array or return the HTTP response code 204 - No Content. Note: A maximum of 500 segments can be sent in the array.	Array of strings

Example

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

Response codes and circuit breaker logic

The following HTTP response code rules and logic apply:

• A 2xx HTTP response code should be returned for successful responses from all partners.

• For cached Data Partners, if Index receives a 5xx error, Index will not cache any data and the request will eventually be retried. If Index receives a 4xx error, Index caches information indicating that the request should not retried, and no enrichment data from the partner is available for the given key.

Circuit breaker logic

If Index receives a 4xx or 5xx error, Index's internal circuit breaker logic is triggered, and requests to the affected partner's API are throttled. Requests to a partner's API that time out will also trigger this same circuit breaker logic. Circuit breaker logic exists to protect both Index and our partners' systems. When errors rates return to nominal levels, circuit breakers will reopen and regular traffic volume will resume.

Cached API response headers

Index will honor the following HTTP response header for Cached API integrations.

Object	Required?	Description
Cache-Control	Optional	The max-age directive is used to communicate how long the data can be used from cache. For partners implementing a cached integration with Index, if this directive is not supplied, we will cache the data for 24 hours and Index will not respect max-age directives exceeding 24 hours.. The no-cache directive will be used to communicate whether the data being returned should be re-validated before it is used again. Responses with this header will be cached, but any time that response is used, Index will reach out to the partner to determine whether the response has changed. This directive can be used while the partner's classification is running.

Response examples

In the following example, Index requests data from a Data Partner's endpoint. The partner returns preliminary enrichment data and wants Index to continue to check back with their endpoint for their complete enrichment data.

"HTTP/1.1 200 OK
Server":"abc
Date":"Fri",
"31 Mar 2020 18":"37":"10 GMT
Content-Type":"text/html;charset=utf-8
Content-Length":"0
Connection":"keep-alive
Cache-Control":"no-cache"{
"segment_ids":[
	"sports_news",
	"football_players"
	]
}
		

In the following example, Index requests data from a partner's endpoint. The partner does not have any data available yet and wants Index to continue to check back with their endpoint for their complete enrichment data.

"HTTP/1.1 200 OK
Server":"abc
Date":"Fri",
"31 Mar 2020 18":"37":"10 GMT
Content-Type":"text/html;charset=utf-8
Content-Length":"0
Connection":"keep-alive
Cache-Control":"no-cache"{
"segment_ids":[
      
]
}"# note":"an empty response body is also acceptable in this situation."
		

In the following example, Index requests data from a partner's endpoint. The partner returns a full classification that should be cached for 24h (86,000 seconds).

HTTP/1.1 200 OK 
Server":"abc 
Date":"Fri",
"31 Mar 2020 18":"37":"10 GMT 
Content-Type":"text/html;charset=utf-8 
Content-Length":"0 
Connection":"keep-alive 
Cache-Control":max-age=86400{
"segment_ids":[
	"sports_news",
	"football_players",
	"arsenal",
	"english_sports",
	"fa_cup"
	]
}
		

Authentication

If you require authentication, Index supports OAuth, as well as, tokens in the query string.