• The purpose of the API is to be able to manage URS redirects. For this we need only a single endpoint.
  • There will be a single resource exposed in the API -> Redirects:
    • GET: Used for retrieving the settings of a single redirect resource
    • POST: for creating new redirects
    • PUT: for updating an existing redirect
    • DELETE: for deleting a single redirect resource

http://urs.pbs.org/api/1.0/

Some generally applicable specifications

  • All relative URLs below are relative to the API entry point.
  • All DATETIME values are considered UTC in both inputs and outputs.  DATETIME are in W3-DTF format which is a subset of ISO 8601
URL: /redirect/

Required Inputs:

  • original_url : URL

    • Not validated (i.e. for 404).

Optional inputs:

  • geo_blocking - can contain one of the following:
  • available_start : DATETIME

  • available_end : DATETIME

Sample redirect creation payload:

{
    "original_url": "<URL>",
    "geo_blocking": {
    	"allow": ["country code", "country code", ...],
    },
    "available_start": "2012-05-17T00:00:00",
    "available_end": "2012-08-17T00:00:00"
}
HTTP/1.0 201 CREATED
Date: <date created>
Server: <server information>
Content-Type: application/json
Location: <URS_BASE_URL>/api/1.0/redirect/<the_new_redirect_key>/

{
    "$self": "<URS_BASE_URL>/api/1.0/redirect/<the_new_redirect_key>/"
    "original_url": "<URL>",
    "protected_url": "<URL>",
    "geo_blocking": {
    	"restrict": ["country code", "country code", ...],
     },
    "available_start": "2012-05-17T00:00:00",
    "available_end": null
}
HTTP/1.0 400 BAD REQUEST
Date: <date>
Server: <server information>
Content-Type: text/html; charset=utf-8
<message>

 

URL: /redirect/<redirect_key>/

Optional inputs:

At least one of the inputs should be present. An empty payload is invalid.

  • original_url : URL

    • We probably should not validate this (i.e. for 404).

  • geo_blocking - can contain one of the following:

    • allow : list of country codes

    • restrict : list of country codes

  • available_start : DATETIME

  • available_end : DATETIME

On success: HTTP 204

On invalid key: HTTP 404

On invalid payload: HTTP 400

URL: /redirect/<redirect_key>/

On bad key: HTTP 404

On success:  HTTP 200

  • original_url

  • protected_url

  • geo_blocking

  • available_start

  • available_end

  • redirect_key

Sample redirect GET response:

{
    "$self": "<URS_BASE_URL>/api/1.0/redirect/<redirect_key>/"
    "original_url": "<URL>",
    "protected_url": "<URL>",
    "geo_blocking": {
    	"restrict": ["country code", "country code", ...],
     },
    "available_start": "2012-05-17T00:00:00",
    "available_end": null
}
 
URL: /redirect/<redirect key>/

On success:

HTTP/1.0 204 NO CONTENT
Date: <date>
Server: <server information>
Content-Length: 0
Content-Type: text/html; charset=utf-8

Bad redirect key:
HTTP 404

Already deleted:

Ideally HTTP 410 but almost surely have to use 404.

We will use a standard authentication method, 2-Legged OAuth for the URS API.

Resources:

Sample request:

GET *<URS_BASE_URL>/api/1.0/* HTTP/1.1
Host: <URS_BASE_URL>
Authorization: OAuth realm="<URS_BASE_URL>/api/1.0/",
    oauth_consumer_key="dpf43f3p2l4k3l03",
    oauth_nonce="kllo9940pd9333jh",
    oauth_timestamp="1191242096",
    oauth_signature_method="HMAC-SHA1",
    oauth_version="1.0",
    oauth_signature="tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D"