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 toput 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