File Retrieval API

This API is for accessing asset files and should be considered Read Only. If you want to truly interact with NetX programmatically — both reading and writing data — then please refer to our JSON/RPC API which provides a complete complement of objects and methods.

This API can also be used to fetch the associated file data (the bytes). File data may include (if available) the following file types:

  • original — the Asset original file.
  • thumb — the thumbnail of the Asset (150 pixels)
  • preview — the preview of the Asset (500 pixels)
  • zoom — the zoom file for the Asset (default is 2000 pixels)
  • flv — if the Asset is a video, and if the system is configured to create FLV proxies for video, then this data should be available.
  • view — retrieve a specific asset "view"; requires that the view name be added as a suffix.
  • constituent — retrieve a specific asset "constituent" (either a "page" or a "keyframe"; requires that the constituent ID be added as a suffix, or you can append "page1", "page2", etc, or you can append "keyframe1", "keyframe2", etc.

To access these files, you need to be authenticated and you need to preface the commands with the "/file" prefix. For example, if you want to retrieve the original file for Asset ID "2", the command looks like this:

/file/asset/2/original
CODE

or, if you need the thumbnail for Asset ID 12345:

/file/asset/12345/thumb
CODE
or, if you need a specific view for Asset ID 12345:
/file/asset/12345/view/previewH264/v_12345.mp4
CODE

or, if you need a specific page (of a PDF for example) for Asset ID 12345:

/file/asset/12345/constituent/page1/1.jpg
CODE

This assumes that the asset in question has a page; the trailing file suffix is not required.

Additionally, you can further specify whether the file should be sent to the browser as an attachment with the "attachment" suffix. Eg:

/file/asset/12345/thumb/attachment
CODE

Effectively, this add the following HTTP header to the response:

"Content-Disposition", "attachment; filename="fileName"
CODE
Where "fileName" is the name of the file returned. This suffix command is typically used in conjunction with browser downloads; this header will typically instruct the User's Web browser to download the file instead of attempting to display it directly.

Parameters

You can also specify that the Content Disposition is an attachment by passing a "attachment" parameter, with a value of "true". Eg: 

/file/asset/2/original/myFile.jpg?attachment=true
CODE

By default, any "original" file accessed — either with the "attachment" directive or not — is recorded as an Asset Delivery in NetX's statistics module (other types, like "thumb", "preview", "view", etc are not recorded as an Asset Delivery). The reason is that the main HTML5 UI also uses this same system to deliver asset files to the end user. So, if you are wanting to retrieve original files without recording it as a "delivery", you can add the "record" parameter and set it to "false". Eg:

/file/asset/2/original/myFile.jpg?record=false
CODE

Authentication

There are a number of ways to authenticate with the REST API; and default, all REST services (and any service) requires proper authentication.

  1. Authenticated Session — if you log in to the main application, this will set your credentials in the server HttpSession; REST commands will utilize this information in servicing requests first and foremost
  2. "viewer.userLogin" Property — if you set the "viewer.userLogin" property to an existing User in the application (or vis-a-via a remote Directory Server), then all REST calls will be made on behalf of the configured user. In this way, an Administrator can add ACL Permission entries to control what is exposed via REST calls based on what that "viewer" User is allowed to access.
  3. "sessionKey" Parameter — you can simply pass a "sessionKey" parameter (via GET or POST) along with the REST command, and that sessionKey — assuming it's valid — will provide the authentication credentials. You can obtain a sessionKey via the Web Services API.
  4. BASIC Auth — all REST commands support the HTTP BASIC authorization system (please refer to RFC 1945 , RFC 2616, and RFC 2617; or see the Wikipedia article: Basic access authentication).