Media API
You can add media to an item during the authoring process. This allows you to create more rich, dynamic, and engaging content. Media is not just for decorative purposes. You can use media to provide candidates with essential contextual information and create unique assessment scenarios, like video case studies and language comprehension tests.
The Media API resource is used to retrieve and upload media.
This article explains what calls can be made to the Surpass API using the Media resource.
Import this API into your Postman Workspace
In This Article
Retrieving media information
Send a request to the endpoint to retrieve information for a specific piece of media using its ID. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/Media/{id} |
Returns information for the specified piece of media, where {id} is the media’s unique identifier. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": null,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": "Geography Subject"
},
"id": 1,
"name": "Map of Europe",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Media/1",
"fileExtension": "mp3"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many pieces of media there are in total. This is null because the information retrieved is for a specific piece of media.
top integer
Details number of pieces of media returned in the response. This is null because the information retrieved is for a specific piece of media.
skip integer
Details how many pieces of media were skipped to display those in the response. This is null because the information retrieved is for a specific piece of media.
pageCount integer
Details how many pages of pieces of media there are. This is null because the information retrieved is for a specific piece of media.
nextPageLink string
The endpoint to call the next page of pieces of media. This is null because the information retrieved is for a specific piece of media.
prevPageLink string
The endpoint to call the previous page of pieces of media. This is null because the information retrieved is for a specific piece of media.
response array
Contains the rest of the response.
subject object
Contains the subject’s information.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
subject/name string
The subject’s name.
id integer
The media’s unique identifier.
name string
The media’s name.
href string
The endpoint to call the media’s information, such as /api/v2/Media/{id} where {id} is the media’s unique identifier.
fileExtension enumeration
The media’s filetype extension. The supported filetype extensions are AVI, BMP, FLV, GIF, JPG, MP3, MP4, MOV, MPEG, PDF, PNG, SWF, WAV, and WMV.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving raw media data
Send a request to the endpoint to retrieve a specific piece of media in Base64 encoded format using its ID. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path MANDATORY |
/api/v2/Media/{id} |
Returns information for the specified piece of media, where {id} is the media’s unique identifier. |
Uploading media to media library
Send a request to the endpoint to upload a piece of media to a specified subject’s media library.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample request
The following request contains the minimum required request body to upload a piece of media to the media library.
{
"subject": {
"reference": "Subject1"
},
"data": "QEBA",
"name": "Map of Europe.jpeg"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
subject object mandatory
Contains the subject’s information.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
sharedResource Boolean optional
Determines whether the media is uploaded as a shared resource. A shared resource is a piece of source material that can be used on multiple items in a test. PDFs must be added as shared resources in order to be opened in the Surpass PDF viewer within the test driver.
htmlString string optional
The HTML content if creating HTML source material.
data string mandatory
The file data in encoded Base64 format.
group object optional
Contains the media group’s information.
group/id integer
The media group’s unique identifier.
name string mandatory
The media’s name. This has to include the filetype extension. The supported filetype extensions are AVI, BMP, FLV, GIF, JPG, MP3, MP4, MOV, MPEG, PDF, PNG, SWF, WAV, and WMV.
description string optional
The media’s alt text.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new piece of media’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Media/1",
"errors": null,
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: