SWITCHcast API V1 – Specification

Checklist

What you need to integrate SWITCHcast into your web service using the SWITCHcast API:

  • API user account on cast.switch.ch and cast-test.switch.ch*
  • SSL certificate for client authentication*
  • Programmer resources
  • Optional: Consider setting up an external access authority for your university

* Please contact the SWITCHcast team for an API account and the corresponding SSL certificate.

Preface

The SWITCHcast API is divided into producer and spectator functions. Spectator functions provide read-only access, whereas producer functions also include write access to the content.

All URLs addressing the production functions start with /api/v1 and allow read- and write access to the resources. The spectator functions are reachable through URLs starting with /api/v1/vod and are strictly for read-only access.

The API is a machine-to-machine interface, but still all calls must be executed in the context of a user. For the production features (/api/v1), only those channels and clips will be returned to which the given user has producer rights. These rights are equivalent to the channel access on the "classic" SWITCHcast web page. 

For the spectator functions, less restrictions apply: All resources (channels/clips) are shown, to which the given user has spectator access. Depending on a channel's configuration, the clips can be visible only to members of the same university, to all SWITCHaai federation members or public to all Internet users. 

To achieve a consistent structure, the resources are hierarchically addressed, using the levels user - channel - clip. Users are identified by their AAI unique ID, channels and clips by their alphanumeric ID.

0. Server communication

The API provides powerful access to most of the SWITCHcast features. Since no AAI protection is possible, we have to ensure a maximum in connection security and level of trust. The server accepts only https connections using client authentication with a certificate. Please contact the SWITCHcast team to get an API certificate issued.

0.1 API Servers

https://api.cast.switch.ch (productive)
https://api.cast-test.switch.ch (test)

0.2 REST API

Each SWITCHcast resource (user, channel, clip) is reachable through a unique URL. The file extension determines the data exchange format. Currently, the API supports XML communication.

0.3 Usage of the HTTP methods

GET: Request data from server

POST: Create a new resource

PUT: Update existing resource

DELETE: Destroy resource

Note:

Some HTTP(s) clients do not support the methods PUT and DELETE. In such cases, you can perform a POST request with the additional parameter _method, setting its value to put or delete respectively.

1. Producer functions

1.1 User lookup and registration

Important:

All calls to the producer features (/api/v1) require a registered user on the SWITCHcast system. The following functions are provided for that matter:

Get XML format for new user:      GET  /api/v1/users/new.xml
Create new user:                  POST /api/v1/users.xml
Check if user exists:             GET  /api/v1/users/unique_id@homeorg.ch.xml

Notes:
 - "unique_id@homeorg.ch" is the user's AAI unique ID
 - Update/delete users is currently not supported

1.2 Channel management

Get all channels for user:        GET    /api/v1/users/unique_id@homeorg.ch/channels.xml
Get XML format for new channel:   GET    /api/v1/users/unique_id@homeorg.ch/channels/new.xml
Create new channel:               POST   /api/v1/users/unique_id@homeorg.ch/channels.xml
Get existing channel:             GET    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s.xml
Get XML format for update channel:GET    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/edit.xml
Update existing channel:          PUT    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s.xml
Delete existing channel:          DELETE /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s.xml

Notes:
 - "unique_id@homeorg.ch" is the user's AAI unique ID. Must be registered beforehand
 - "2m1e3qpd7s" is the alphanumeric channel ID

1.3 Clip management

Get clips for existing channel:   GET    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips.xml
Get XML format for new clip:      GET    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips/new.xml
Create a new clip:                POST   /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips.xml
Get details for a clip:           GET    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips/387s1lpgo.xml
Get XML format for update clip:   GET    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips/387s1lpgo/edit.xml
Update existing clip:             PUT    /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips/387s1lpgo.xml
Delete existing clip:             DELETE /api/v1/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips/387s1lpgo.xml

Notes:
 - "unique_id@homeorg.ch" is the user's AAI unique ID. Must be registered beforehand
 - "2m1e3qpd7s" is the alphanumeric channel ID
 - "387s1lpgo"  is the alphanumeric clip ID

2. Spectator functions

Not all channels and clips have access restrictions for the spectators, therefore there is no general obligation to register a user when accessing

/api/v1/vod

URLs. In some cases, the spectator does not even have a SWITCHaai account. To maintain the URL structure in such cases, please insert

anonymous@cast.switch.ch

as value for the AAI unique ID.

2.1 Channel listing

Get all channels for user:        GET    /api/v1/vod/users/unique_id@homeorg.ch/channels.xml
Get details for channel           GET    /api/v1/vod/users/unique_id@homeorg.ch/channels/2m1e3qpd7s.xml

Notes:
 - "unique_id@homeorg.ch" is the user's AAI unique ID. Must be registered beforehand
 - "2m1e3qpd7s" is the alphanumeric channel ID

2.2 Clip listing

Get all clips for channel:        GET    /api/v1/vod/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips.xml
Get details for clip              GET    /api/v1/vod/users/unique_id@homeorg.ch/channels/2m1e3qpd7s/clips/387s1lpgo.xml

Notes:
 - "unique_id@homeorg.ch" is the user's AAI unique ID. Must be registered beforehand
 - "2m1e3qpd7s" is the alphanumeric channel ID
 - "387s1lpgo"  is the alphanumeric clip ID