simplex API
Introduction
The simplex metadata API is based on the openAPI3.0 standard in compliance with RFC7231
It consists of the herein fully documented API endpoints and can be tried out interactively:
Overview
| Endpoint | Function | Access | Response |
| /login | Login | Author API key |
30min valid access token & |
| /refresh_token | Refreshing an Access token | Bearer token (refresh_token) |
30min valid access token & |
| /api/v1/* | Author/Profile/Projects content manipulations | Bearer token | JSON |
| /api/v1/public/* | Publicly accessible Channel- and Project metadata endpoint | JSON | |
| /upload | Uploading video- or thumbnail files | Bearer token | |
| /encode | Encoding uploaded video files | Bearer token |
Quickstart
We will assume that you're using the simplex public cloud. Adapt the serverURL for your private or onpremise installation.
1. Login
Use your author or customer credentials to make a first call to the login endpoint that returns a valid access token for all endpoints:
curl -X POST https://media10.simplex.tv/login \
-H "Accept: application/json" \
-d "username=yourAuthor" \
-d "password=yourPassword"
Hint: Use the returned access tokens for authentication in any further calls. You can refresh an access token for longer session:
curl -X POST https://media10.simplex.tv/refresh_token \
-H 'Authorization: Bearer YourRefreshToken'
2. Create a project
curl -X POST "https://media10.simplex.tv/api/v1/projects"
-H "accept: application/json" \
-H "authorization: bearer YourAccessToken" \
-H "Content-Type: application/json" \
-d "{\"title\":\"string\",\"description\":\"string\",\"state\":\"ONDEMAND\",\"authScheme\":\"NONE\",\"eventDate\":\"2019-10-11T08:59:51.305Z\",\"enabled\":true,\"isPublic\":true,\"publisher\":\"string\",\"details\":\"string\"}"
This call returns a JSON object containing an identifier to the created project. It consists of a customerID, authorID & projectID. Store them for further reference.
3. Upload a video file
For uploading to simplex, a TUS client is required. See chapter Example Code to get you going.
Video files are usually very large, thus resumable uploading is a must feature. TUS allows this by defining package sizes that are subsequently uploaded and will be automatically retried upon failure.
url = "https://media10.simplex.tv/upload/{}/{}/{}/".format(customer_id, author_id, project_id)
headers = {'authorization': 'bearer ' + self.token() }
metadata = {"filename": remote_file_name}
As can be seen, the endpoint requires the values for customer_id, author_id and project_id from the last step & a remote filename which will be used on the next step.
4. Encode a videofile
To start encoding a uploaded video, only the projectID & the remote_filename are required:
curl -X GET https://media10.simplex.tv/encode/project_id/remote_filename \
-H "authorization: bearer YourAccessToken"
Congratulations, with these basic steps you should have an uploaded & encoded project ready to be accessed for your viewers under:
https://media10.simplex.tv/content/customer_id/author_id/project_id/
Public API Access
xtendx supplies two public(unauthenticated) API endpoints that can be invoked from any frontend:
1) https://media10.simplex.tv/api/v1/public/projects/
2) https://media10.simplex.tv/api/v1/public/channels/
1) Get a list of Projects
Endpoint: https://media10.simplex.tv/api/v1/public/projects/
Required argument: customerId
Returns: All projects having enabled:true & is_public:true are returned on this endpoint. If channelIds parameters are provided, additionally, those channel-Informations will be returned.
Example #1:
This call returns a descendingly sorted list by creation date:
https://media10.simplex.tv/api/v1/public/projects/?customerId=2&sort=createdDate:desc
Hint: Consult the metadata information via OpenAPI editor & look for "/public/projects/" to find all options about filtering & sorting.
Example #2:
This call returns a list of projects in either of two specific channels in ondemand state with pagination of 15 projects/page and querying the first page:https://media10.simplex.tv/api/v1/public/projects/?customerId=2&channelIds=1112&channelIds=1164&state=ONDEMAND&size=15&page=0
The returned JSON object has the following structure:
{
"totalPages": 2,
"totalElements": 20,
"number": 0,
"size": 15,
"numberOfElements": 15,
"projects": [
{
"projectId": 56719,
"title": "013 - What is Simplex Pro (Final Englisch)",
...
"channels": [
{
"channelId": 1112
}
},
...
],
"channels": [
{
"channelId": 1112,
"title": "simplex Produkte",
...
},
{
"channelId": 1164,
"title": "channeldemo",
...
}
]
}
2) Get a list of channels details
Endpoint: https://media10.simplex.tv/api/v1/public/channels/
Required arguments: customerId & at least one channelIds
Returns: A list of channels metadata by channelId's
Example:
https://media10.simplex.tv/api/v1/public/channels/?customerId=2&channelIds=144&channelIds=197
The returned JSON object has the following structure:
{
"totalPages": 1,
"totalElements": 2,
"number": 0,
"size": 20,
"numberOfElements": 2,
"content": [
{
"channelId": 144,
"title": "Test Channel 1",
"description": "this is the first test channel",
"numberOfElements": 3,
"customerId": 2,
"customerCompany": "xtendx AG",
"createdDate": "2009-10-05T17:19:11.000+02:00",
"updatedDate": "2013-12-10T13:24:34.000+01:00"
},
...
]
}
Access static files (e.g project thumbnails)
Posterfame, original size: simvid_1.jpg
Example: https://media10.simplex.tv/content/2/3945/63946/simvid_1.jpg
Posterframe medium: simvid_1_med.jpg
Example: https://media10.simplex.tv/content/2/3945/63946/simvid_1_med.jpg
Posterframe small: simvid_1_sml.jpg
Example: https://media10.simplex.tv/content/2/3945/63946/simvid_1_sml.jpg
Example Code
We provide an example python code for your simplex access class here:
Further readings
TUS Client
Uploading to simplex requires the use of TUS ( https://tus.io/implementations.html ). Clients exist in every mayor programming language. See one possible usage example in our provided python script.
Authentication Workflow (Login)
Authentication Workflow (Refresh)
Upload Workflow
Custom Metadata
If the provided project metadata fields are not sufficient, there exists a "details" metadata field which can be used to store additional key/value or other content.
See this simple example that can be used for editing (or creating) a project on simplex:
detailsJSON = """
{
"param1": "value 1",
"param2": 123,
"param3": true
}""".replace('\n',' ').replace(' ','')
simplex.editProject(project_id = 12345, title = 'myProject', details=detailsJSON))
If you have any further questions, don't hesitate to contact us under support@xtendx.com
You weren't able to find whet you were looking for? Contact us now.
Our support team is available
from Monday until Friday
from 9 am until 5 pm.
You will get an answer from us within 24 hours.
In urgent cases (system failure) outside office hours, please call our emergency service: +41 44 580 97 16
Customers who have booked Live Support can use the number assigned to them.
More support articles
ADFS/SAML activation
22.10.2019
Peer-to-Peer
01.03.2017
Caching
01.03.2017
Multicast
01.03.2017
