HomeGuidesChangelog
Guides

API Endpoints

Suggest Edits

Retrieving Identifiers - /v2/map and /map

v2/map

Sidecar v2 introduces a new endpoint, presented under /v2/map, that allows for decryption of a single envelope to multiple available IDSources.

It accepts three parameters: a required “env=[envelope identifier]” parameter an optional “sid=[seat ID]” parameter that can refer to a single seat, or repeat for multiple seats and an "idsource=[idsource string"]. The /v2/map endpoint returns a JSON array of objects containing an identifier source as well as one or more seat mappings.

$ curl -v 'localhost:5000/v2/map?env=AutVJed5qoEQ6hvuS9OharoNa8tyk1Hoa2nz8hv-50SASJb7TkzxhgeHnknLDVXvs5GGv-8V_CUdtNztqQmLvwUxIlA'
> GET /v2/map?env=AutVJed5qoEQ6hvuS9OharoNa8tyk1Hoa2nz8hv-50SASJb7TkzxhgeHnknLDVXvs5GGv-8V_CUdtNztqQmLvwUxIlA HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 3528
<
[{"source":"liveramp.com","mapping":{"SEAT0029":"XY0029yIz8i7-uBNtfZXdP5LFtsxjb4B82Om-ZrJh8rpo-rjU","SEAT0030":"XY00301decxLOMNZn7W7MAgLlwUcU1ODM1xag_U5IFDRY_IDo"}},"source":"uidapi.com","mapping":{"SEAT0029":"AgAAAAPHpn5cHG8VyP6CAuHh5AMemVXXXxMdVzjhmdRl0nt8cglqmMRWTmKap05HIeNpLvEaAERX2mLp0RVSJz0M48igDHx53dsrnaenCAG/VDTJcAkHFLIplzOFjYASu0wtXsJ3IBNAWjSABjs7xmEXq73B16HRZAeCCBBKGBdvhp0rww==","SEAT0030":"AgAAAAPHpn5cHG8VyP6CAuHh5AMemVXXXxMdVzjhmdRl0nt8cglqmMRWTmKap05HIeNpLvEaAERX2mLp0RVSJz0M48igDHx53dsrnaenCAG/VDTJcAkHFLIplzOFjYASu0wtXsJ3IBNAWjSABjs7xmEXq73B16HRZAeCCBBKGBdvhp0rww=="}]

If “sid” parameters are used, only the provided Seat IDs and associated IdentityLinks will be included in the output. If no "sid" parameter is included, the endpoint returns identifiers for all available seats the sidecar is authorized for.

/map (V1)
The original /map endpoint will continue to offer envelope resolution to a single IDSource. The IDSource can be specified at runtime and defaults to liveramp.com. For "v1" /map requests, a new header (X-IDL-Mapper-ID-Source) has been added to the response that will specify the IDSource contained in the response, for example:
X-IDL-Mapper-ID-Source: liveramp.com

The idsource query parameter can be applied to "v1" /map requests to override the default IDSource.

Otherwise, behavior is unchanged from previous versions.

Both /map endpoints are intended to always return a quick response, even in the event the sidecar becomes unauthorized. There is no need to query the /health endpoint prior to each request. Note that /map will not follow the 503 behavior on startup; it will always return either a 200, 204, 401 or 410 status code.

  • 200 indicates a successful lookup.
  • 204 indicates that the envelope contained data not authorized for certain partners
  • 401 is a sign that there was a problem with authenticating the Sidecar -- sustained 401 responses may signal a need to restart the Sidecar and check that it is able to reach the check-in service.
  • 410 is returned when an envelope has expired -- check your envelope source and reduce any caching.
  • 500 (Internal Server Error) status code will be thrown if something unexpected goes wrong within the Sidecar, but this is unexpected behavior. We recommend documenting requests that cause this behavior and reporting them to LiveRamp. The sidecar will report telemetry on such failures back to LiveRamp for production sidecar builds.

In a production environment, Seat IDs will be provided by the SSP and mapped by LiveRamp. To add new mapping or change existing seat IDs, contact LiveRamp Product Operations.

Checking Sidecar Status - /health

Use the health check endpoint to check the status of the sidecar without running through envelopes. It takes no arguments and returns a JSON response, along with a transparent HTTP status code to indicate the sidecar’s status.

$ curl -v localhost:3000/health
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 5000 (#0)
> GET /health HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 49
<
* Connection #0 to host localhost left intact
{"last_successful_authentication":0,"keys_ttl":0}* Closing connection 0
  • 200 (OK) indicates that the sidecar is authorized and ready to accept /map requests.
  • 503 (Service Unavailable) indicates that the sidecar has started, but has not yet successfully completed its initial authorization routine. Under normal operation, a sidecar should never stay in this state for an extended period of time. Seeing this code for an extended period could indicate that the sidecar is unable to reach LiveRamp servers. In this case, please contact LiveRamp.
  • 401 (Unauthorized) indicates that the sidecar has contacted LiveRamp, but LiveRamp has denied the request for keys. A sidecar may go into this state during the course of operation if LiveRamp revokes authorization remotely, or if the container loses connectivity and the authorization times out.

last_successful_authentication is a UNIX timestamp in seconds of the last time LiveRamp re-authorized the sidecar instance.

keys_ttl is a UNIX timestamp in seconds of when the current authorization will expire -- it will be equivalent to the last_successful_authentication + four hours.

Monitoring Sidecar - /metrics

You can check to see how much data a sidecar instance is processing (and at what internal latency) by calling the /metrics API endpoint. 

$ curl localhost:5000/metrics 
{
  "map_latency_50_percentile": 116300,
  "map_latency_90_percentile": 181400,
  "map_latency_99_percentile": 1.56745e+06,
  "query_count": 3779,
  "bad_request_count": 0
}

This will return the number of requests processed, the subset which were bad requests and latency (measured in nanoseconds) at various percentiles.

Adding /prometheus will return the metrics in Prometheus metric format: 

$ curl localhost:3000/metrics/prometheus
# HELP bad_request_count Number of bad requests per minute
# TYPE bad_request_count gauge
bad_request_count 0
# HELP map_latency_50_percentile 50th percentile latency number
# TYPE map_latency_50_percentile gauge
map_latency_50_percentile 114400
# HELP map_latency_90_percentile 90th percentile latency number
# TYPE map_latency_90_percentile gauge
map_latency_90_percentile 180800
# HELP map_latency_99_percentile 99th percentile latency number
# TYPE map_latency_99_percentile gauge
map_latency_99_percentile 937850
# HELP query_count Number of queries processed in a minute
# TYPE query_count gauge
query_count 3642

Updated about 5 years ago