---
title: "Registering and Managing URS Links"
canonical: "https://docs.pbs.org/space/URS/3577374/Registering%20and%20Managing%20URS%20Links"
format: markdown
---
> Macro (toc)

## URS API interface

- 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

## API Entry Point

> ℹ️ 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](http://www.w3.org/TR/NOTE-datetime) format which is a subset of ISO 8601

## Methods

### **POST (Create Redirect)**

`URL: /redirect/`

**Required Inputs:**

- ***original_url*** : URL
  - **Not** validated (i.e. for 404).

**Optional inputs:**

- ***geo_blocking*** - can contain **one **of the following:
  - ***allow*** : list of country codes OR
  - ***restrict*** : list of country codes  
Country codes can be found here: [http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
- ***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"
}

```

#### Output:

##### On success:

```
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
}
```

##### On invalid payload:

```
HTTP/1.0 400 BAD REQUEST
Date: <date>
Server: <server information>
Content-Type: text/html; charset=utf-8
<message>

```

 

### **PUT (Update Redirect)**

`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

#### Output:

**On success:** HTTP 204

**On invalid key:** HTTP 404

**On invalid payload:** HTTP 400

### **GET (View Redirect)**

`URL: /redirect/<redirect_key>/`

#### Output:

**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
}

```

` `

### **DELETE (Delete Redirect)**

`URL: /redirect/<redirect key>/`

#### Output:

**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.

## Security

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

Resources:

- [http://pypi.python.org/pypi/oauth2/1.5.211](http://pypi.python.org/pypi/oauth2/1.5.211)

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"

```