DF Studio provides a REST API for uploading images. Clients can post to the desired location in DF Studio (i.e. the path in the Library), and the API does its best to put the file there. The server handles folder and Project creation, prevents duplicates, and works on filenames, not IDs. (DF Studio internal IDs are used to create permanent URLs but should not be constructed by the client.)
Being REST-based, GET will only ever return data, and is safe to call repeatedly. POST is used to insert/update/save a record. Resources are arranged in a path-like hierarchy.
The Upload API requires authentication and uses session IDs in URLs. Files can only be uploaded through the Upload API; they cannot be downloaded. (Downloading is only allowed from the Asset API.)
Documentation Conventions
Throughout this document, observe the following placeholder values:
- [BASE]: example_company.dfstudio.com
- [SID]: replace with the session id
Example URL
Uploading a file (once authenticated)
POST -> example_company.dfstudio.com/rest/v3/session/SESSION_ID/path/[FOLDER]/PROJECT/FILENAME.EXT?type=image
- example_company.dfstudio.com/rest/v3: the root of the Upload API
- session: the session resource used to authenticate
- SESSION_ID: a client’s unique session
- path: the path resource used to create folders, project and upload files
- FOLDER: the folder to place the project in (can be a path / subfolder), optional
- PROJECT: the Project name, required
- FILENAME.EXT: the name of file being uploaded. Extension is important for proper MIME type handling.
- type=image: use image to upload files
Resources
- Session: the root resource all resources are nested under
- Path: the resource which handles creating folder, Projects, and image for a given uploaded file
General Ideas
The Upload API supports three data syntaxes: JSON, XML, and HTML. The data syntax is specified by appending the http parameter rest.syntax with one of the syntaxes above, in all lowercase. The default is
rest.syntax=json
Session Resource
The session resource is used to authenticate to the Upload API. Authentication is required, and once authenticated the client must use the URL returned for all future requests.
To Authenticate, POST the following HTTP parameters to the session URL:
- username
- account
- password
Path Resource
The Path resource requires the HTTP parameter type to indicate what object type to operate on.
- project: Information on a single Project
- projects: A list of Projects in the current folder
- folder: Information on a single folder
- folders: A list of folders in the current folder
- image: Used to upload files
URL Parameters
- depth=[local],all: List in folder, or all folders from this point down
- structure=[flat],hierarchy: flat: List folder names, hierarchy: Only applies if depth=all
- ignore-folders=[false],true: If true will list Projects independent of their containing folders
Working with Images
Upload an image file matching on Setup in Project, or creating new if not found:
GET|POST:[folder/folder_path/]project_name/image_name.ext?type=image[&setup=name][&ignore-folders=true][&rest.syntax=json]
HTTP Methods
- POST: upload image
- GET: verify image exists
URL Parts
- folder_path: Folder path, will be created if does not exist (optional, defaults to root folder, see ignore-folders above)
- project_name: Project name (required)
- image_name.ext: Image name; file extension is optional but is recommended
URL Parameters
- setup=name: Specify the name of Setup, or attempt to extract from image name, or default
- ignore-folders=[false],true: If true will search for Project in any folder, and if not found and POSTing will create in root folder (default false)
POST BODY: Binary of image
RETURNS: Name and ID of image, nothing more.
Examples
GET:[BASE]/rest/v3/session/[SID]/path.json?type=folders&depth=all&structure=hierarchy
RESPONSE: JSON
{ "folders": [ { "id": "f_1", "name": "ExampleFolder", "path": "/ExampleFolder", "pathRelative": "/ExampleFolder", "url": "https://[BASE]:443/rest/v3/session/[SID]/path/%28%28folder%3Af_1%29%29/ExampleFolder.json" "allowsCreate": true, "folders": [{ "id": "f_295", "name": "Show Title", "path": "/ExampleFolder/Show Title", "pathRelative": "Show Title", "url": "https://[BASE]:443/rest/v3/session/[SID]/path/%28%28folder%3Af_2%29%29/Show+Title.json" "allowsCreate": true, "folders": [ { "id": "f_3", "name": "Season 1", "path": "/ExampleFolder/Show Title/Season 1", "pathRelative": "Season 1", "url": "https://[BASE]:443/rest/v3/session/[SID]/path/%28%28folder%3Af_3%29%29/Season+1.json" "allowsCreate": true, "folders": [], }, { "id": "f_4", "name": "Season 2", "path": "/ExampleFolder/Show Title/Season 2", "pathRelative": "Season 2", "url": "https://[BASE]:443/rest/v3/session/[SID]/path/%28%28folder%3Af_4%29%29/Season+2.json" "allowsCreate": true, "folders": [], } ], }], } ], "info": { "count": 4, "limit": 0, "offset": 0, "order": "", "returned": 4 } }
POST:[BASE]/rest/v3/session/[SID]/path/ep_109/image_001.jpg?type=image
image "image_001", setup default, project "ep_109" , folder root
POST:[BASE]/rest/v3/session/[SID]/path/shows/ep_109/image_001.jpg?type=image
image "image_001", setup default, project "ep_109", folder "shows"
POST:[BASE]/rest/v3/session/[SID]/path/ep_109/image_001.jpg?type=image&setup=cast
image "image_001", setup "cast", project "ep_109", folder root
POST:[BASE]/rest/v3/session/[SID]/path/ep_109/image_001.jpg?type=image&ignore-folders=true
image "image_001", setup default, project "ep_109" (in any folder, or create in root folder)
POST:[BASE]/rest/v3/session/[SID]/path/ExampleFolder/show_title/ep_109/image_001.jpg?type=image
image "image_001", setup default, project "ep_109", folder "ExampleFolder/show_title"
GET:[BASE]/rest/v3/session/[SID]/path/ExampleFolder/show_title/ep_109/image_001?setup=exteriors
get image id and name if exists or returns 404
Upload Directly to S3
The Upload API also allows direct-to-S3 uploading. This is the preferred upload method because it reduces load on DF Studio servers and is likely to provide better direct throughput to the upload client.
To post files directly to S3, a client must first request a pre-authenticated URL by posting to the image URL with the additional HTTP Parameter action=uploadURLRequest.
A temporary/pre-authenticated URL will be returned to the client so that the file’s binary data can then be transmitted to this URL using HTTP PUT.
Finally, once the upload to S3 is complete, the client must callback to the Upload API by POSTing to a callback URL to indicate a successful upload.
1. Post to image URL with additional parameter (no file data)
- action=uploadurlrequest
- contentType=? (this is optional)
Will return the following data:
- uploadUrl: The S3 URL to PUT the file data to
- uploadContentType: The contentType to use when PUTing to S3 (must use this value)
- uploadUrlExpires: The expiration date of the the upload URL
- uploadOnCompleteUrl: The URL to POST to after the S3 Upload has completed. (required step)
2. PUT file data to s3 pre-authenticated URL, using contentType returned in step 1.
3. POST to the uploadOnCompleteUrl returned in step 1 to signal DF Studio to process the file.
Example Code
An example Java client is available in GitHub, demonstrating the use of this API.