REST API - Media - Overview

Media represent text and audio files that may be uploaded and shared as resources for use in Ribbit applications. Typical examples of Media files include prompts for IVR applications, and recorded or transcribed content from voicemail or similar applications. Media or any other types of files are stored in a Domain-level virtual file system. In /media/, a user can create folders, upload files to those folders, and designate access control lists (ACL) for those files and folders, which other users and applications within the same Domain can access.

By default, the user that creates a file or folder is able to access that file or folder. The user can set an ACL to determine which other users and applications can access that file or folder. When a user creates an ACL, only the users in that ACL have access to that file or folder. The user who creates the ACL should remember to add himself to the list. Furthermore, when a user adds an application (for namesake, call it "exampleApp") to the ACL without specifying users, then exampleApp's users can only access the file or folder. If there was another application in the same Domain that was not mentioned in the ACL, then that application or its users cannot access that file or folder.

REST API - Media - Methods

Method	Resource	Response	Notes
GET	/media/<domain>/<callId>/<callId>.mp3	(200) File download	Download voicemail as MP3.
GET	/media/<domain>/<folder>	(200) Folder details	Retrieves a specified folder.
GET	/media/<domain>/<folder>/acl	(200) Folder details	Retrieves permissions for a specified folder.
PUT	/media/<domain>/<folder>/acl	(202) Modified	Updates permissions for a specified folder.
DELETE	/media/<domain>/<folder>	(204) No Content	Deletes the specified folder.
GET	/media/<domain>/<folder>/<file>	(200) File Details	Retrieves a specified file.
GET	/media/<domain>/<folder>/<file>/acl	(200) File Details	Retrieves permissions for a specified file.
PUT	/media/<domain>/<folder>/<file>/acl	(202) Modified	Updates permissions for a specified file.
DELETE	/media/<domain>/<folder>/<file>	(204) No Content	Deletes the specified file.
POST	/media/<domain>	(201) Location	Creates a folder.
POST	/media/<domain>/<folder>	(201) Location	Creates a file.
GET	/media/<domain>	(200)	Lists visible folders in a Domain.

REST API - Media - Properties

Name	Methods	Value	Notes
id	GET, POST, PUT	string	(req) Unique Media identifier.
createdWith	GET	string	Application ID used to create the folder/file.
createdBy	GET	string	GUID of the developer creating the folder/file.
createdOn	GET	string	The date the folder/file was created.
readUsers	GET, PUT	string	Grants the User the ability to read the folder/file.
readApps	GET, PUT	string	Grants the Application the ability to read the folder/file.
writeUsers	GET, PUT	string	Grants the User the ability to modify the folder/file.
writeApps	GET, PUT	string	Grants the Application the ability to modify the folder/file.

REST API - Media - Examples

Creating a Folder

To create a folder send a POST request with a folder name. In the example below a folder called "mymp3folder" is created. A successful request will return a 201 Created response along with the folder location.

<< POST /rest/1.0/media/domainone
   { "id":"mymp3folder"]}

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/media/domainone/mymp3folder

Deleting a Folder

To delete a folder send a DELETE request with a folder name. In the example below a folder called "mymp3folder" is deleted. A successful request will return a 204 No Content response.

<< DELETE /rest/1.0/media/domainone/mymp3folder
   
>> 204 No Content

Retrieving a Folder

In the example below a GET request with a folder name is used to retrieve details about the folder. As shown the response contains information about all the files in the specified folder. In this case the "mymp3folder contains two files. The "readUsers" and "writeUsers" permissions are are also returned for each file.

<< GET /rest/1.0/media/domainone/mymp3folder
   
>> 200 OK
   { "entry" : {
       "id":"mymp3folder/file1","createdWith":"myAppId","createdBy":"972ee92d-dead-beef-927f-7a92e40f8490",       "dest":"tel:3035552222","startTime":"2001-01-01T08:00:00Z",
       "createdOn":"2009-01-03T01:02:03Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490",
       "writeUsers":["972ee92d-dead-beef-927f-7a92e40f8490"],"size":1234},{"id":"mymp3folder/file2","createdWith":"myAppId", 
       "createdOn":"2009-01-03T04:05:06Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490"],
       "writeUsers":["972ee92d-dead-beef-927f-7a92e40f8490"],"size":5678}]}

File Management

The following examples provide information on file management.

Creating a File

To create a file send a POST request with the name of the folder the file will belong to and file. In the example below a file called "file1" is created in "mymp3folder". A successful request will return a 201 Created response along with the file location.

<< POST /rest/1.0/media/domainone/mymp3folder
   { "id":"file1"]}

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/media/domainone/mymp3folder/file1

Deleting a File

To delete a file send a DELETE request with the file name. In the example below a file called "file1" is deleted. A successful request will return a 204 No Content response.

<< DELETE /rest/1.0/media/domainone/mymp3folder/file1   
 
>> 204 No Content

Uploading a File

Use the following example to upload a file.

<< POST /rest/1.0/media/domainone/mymp3folder/file1 
   { Accept-Type: application/octet-stream]}

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/media/domainone/mymp3folder/file1

Downloading a File

Use the following example to download a file.

<< GET /rest/1.0/media/domainone/mymp3folder/file1 
   { Accept-Type: application/octet-stream]}

>> 200 OK
   <filedata>

Downloading a Voicemail File

Use the following example to download a voicemail file.

<< GET /rest/1.0/media/domainone/mymp3folder/file1 
   { Accept: audio/mpeg]}

>> 200 OK
   <filedata>

Retrieving a Voicemail MP3 File

The filename and path for voicemail files is typically determined by the caller ID of the corresponding call, but is authoritatively listed in the ‘mediaItems’ array property of the corresponding Message resource. Only the owner of the voicemail message is able to download the voicemail audio file.

<< GET /rest/1.0/media/call:26919119/26919119.mp3

>> 200 OK  
   <fileData>

Setting a Folders Read Permissions

To edit a folders read permission send a PUT request with the folder name, "readUser" and the Application GUID. This will enable the users to view the files in the folder.

<< PUT /rest/1.0/media/domainone/mymp3folder/acl
   { {"readUser":["972ee92d-dead-beef-927f-7a92e40f8490"]}

  >> 200 OK
   { "entry" : {
       "id":"mymp3folder","createdWith":"myAppId","createdBy":"972ee92d-dead-beef-927f-7a92e40f8490", "createdOn":"2009-01-03T01:02:03Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490",
       }]}

Setting Read and Write Permissions for a Folder

To set a folders read and write permissions send a PUT request with the folder name, "readUser", "writeUser", and the Application GUID. This will enable the users to read and modify the contents of the folder.

<< PUT /rest/1.0/media/domainone/mymp3folder/acl
   {"readUser":["972ee92d-dead-beef-927f-7a92e40f8490"],"writeUser":["972ee92d-dead-beef-927f-7a92e40f8490"]}

  >> 200 OK
   { "entry" : {
       "id":"mymp3folder","createdWith":"myAppId","createdBy":"972ee92d-dead-beef-927f-7a92e40f8490","createdOn":"2009-01-03T01:02:03Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490",
       "writeUsers":["972ee92d-dead-beef-927f-7a92e40f8490"}]}

Removing a Folders Write Permission

How do I do this is it possible?

<< PUT /rest/1.0/media/domainone/mymp3folder/acl
   {

Retrieving ACL Permissions for a Folder

In the example below a GET request with a folder name is used to retrieve details about all the files in the specified folder and the relevant ACL permissions.

<< GET /rest/1.0/media/domainone/mymp3folder/acl
   
>> 200 OK
   { "entry" : {
"id":"mymp3folder/file1","createdWith":"myAppId","createdBy":"972ee92d-dead-beef-927f-7a92e40f8490","createdOn":"2009-01-03T01:02:03Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490",
"writeUsers":["972ee92d-dead-beef-927f-7a92e40f8490"],"size":1234},{"id":"mymp3folder/file2","createdWith":"myAppId","createdBy":"972ee92d-dead-beef-927f-7a92e40f8490",
"createdOn":"2009-01-03T04:05:06Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490"],"writeUsers":["972ee92d-dead-beef-927f-7a92e40f8490"],"size":5678}]}

Setting a Files Read Permissions

To edit a files read permission send a PUT request with the file name, "readApps" and the application GUID.

<< PUT /rest/1.0/media/domainone/mymp3folder/file1/acl
   { {"readApps":["972ee92d-dead-beef-927f-7a92e40f8490"]}

  >> 200 OK
   { "entry" : {
       "id":"mymp3folder/file1","createdWith":"myAppId","createdBy":"972ee92d-dead-beef-927f-7a92e40f8490"","createdOn":"2009-01-03T01:02:03Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490",
       readUsers":["972ee92d-dead-beef-927f-7a92e40f8490"],"readApps":["myAppId"],]}]}

Setting Read and Write Permissions for a File

To set a files read and write permissions send a PUT request with the file name, "readApps", "writeApps", and the application GUID. This will enable the users to read and modify the file.

<< PUT /rest/1.0/media/domainone/mymp3folder/file1/acl
   {"readApps":["972ee92d-dead-beef-927f-7a92e40f8490"],"writeApps":["972ee92d-dead-beef-927f-7a92e40f8490"]}

  >> 200 OK
   { "entry" : {
       "id":"mymp3folder/file1","createdWith":"myAppId","createdBy":"972ee92d-dead-beef-927f-7a92e40f8490","createdOn":"2009-01-03T01:02:03Z","readUsers":["972ee92d-dead-beef-927f-7a92e40f8490",
       "writeUsers":["972ee92d-dead-beef-927f-7a92e40f8490"}]}

Removing a Files Write Permission