So what happens when you get a URS link?
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.
Using the URS protected link
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 link | HTTP 404 |
Your IP is:
| HTTP 403 |
The current time is before the allowed time window | HTTP 404 |
The current time is after the allowed time window | HTTP 410 |
All other times... | |
(Unless alternate formats are requested - see below) | HTTP 302 |
Alternate Formats
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
JSON redirect
There are two ways to access a protected URL and receive a JSON response (not HTTP Redirect):
- By providing format as a query parameter: http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=json
- 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):
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}
If the Redirect is available:
{"url": "http://google.com", "status": "ok", "message": null, "http_code": 302}
JSONP redirect
There are two ways to access a protected URL and receive a JSONP response (not HTTP Redirect)
- By providing format and callback as query parameters:
http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=jsonp&callback=mycallback - 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:
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})
If the Redirect is available:
mycallback({"url": "http://google.com", "status": "ok", "message": null, "http_code": 302})