First, it looks like:  http://urs.pbs.org/redirect/some-uid-here

An example:  http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3

The above URL redirects the client to original url and provides a 302 HTTP status code.  

The above link is non-functioning and was created for the sole purpose of illustrating the concepts here.

If you load this url in a browser or software, then URS will follow this decision flow:

If...URS returns...
The protected link does not match any known registered linkHTTP 404

Your IP is:

  1. Detected to not be in a country that matches the allowed list or in a country that is on the restricted list 
  2. Detected to be coming from a VPN proxy, and you are attempting to access a show which restricts anonymous IPs. (Anonymous IP restriction applies only to a small number of specific shows, not all PBS content.)
HTTP 403
The current time is before the allowed time windowHTTP 404
The current time is after the allowed time windowHTTP 410
All other times...
(Unless alternate formats are requested - see below)HTTP 302

Sometimes, you don't want just the HTTP 302 redirect.  For example, this is not generally useful in a javascript AJAX call.  Thus, URS exposes some additional functionality

There are two ways to access a protected URL and receive a JSON response (not HTTP Redirect):

  1. By providing format as a query parameter:  http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=json
  2. The second option is to provide "application/json" in Accept header.  http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3

In both cases the response will be one of the following (200 HTTP status code):

  1. If the Redirect is expired, the following response is returned:

    {"url": null, "status": "error", "message": "Redirect is no longer available", "http_code": 410}

    If the Redirect doesn't exists or is not yet available the following code is returned:

    {"url": null, "status": "error", "message": "Redirect does not exist or is not yet available", "http_code": 404}

    If the Redirect is blocked due to a geo-restriction or because the particular show does not allow anonymous IPs, the following code is returned:

    {"url": null, "status": "error", "message": "Redirect is unavailable in your region", "http_code": 403}

  2. If the Redirect is available:

    {"url": "http://google.com", "status": "ok", "message": null, "http_code": 302}

There are two ways to access a protected URL and receive a JSONP response (not HTTP Redirect)

  1. By providing format and callback as query parameters:
    http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=jsonp&callback=mycallback
  2. The second option is to provide "application/javascript" in Accept header and callback method in "X-JSONP-Callback" custom header
    http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3

In both cases 400 HTTP status code is returned if the callback query param is missing or no value is specified. If everything is ok, 200 HTTP status code is returned with the following body:

  1. If the Redirect is expired, will return the following response is returned:

    mycallback({"url": null, "status": "error", "message": "Redirect is no longer available", "http_code": 410})

    If the Redirect doesn't exists or is not yet available the following code is returned:

    mycallback({"url": null, "status": "error", "message": "Redirect does not exist or is not yet available", "http_code": 404})

    If the Redirect is geoblocked, the following code is returned:

    mycallback({"url": null, "status": "error", "message": "Redirect is unavailable in your region", "http_code": 403})

  2. If the Redirect is available:

    mycallback({"url": "http://google.com", "status": "ok", "message": null, "http_code": 302})