• Corporate
• Management Portal
• Developer
• Support

• Downloads
• Forums
• Blogs

Nirvanix API Developer's Guide PDF

Getting Started: An introduction to key concepts

What is an Internet File System?

When to use an IFS?

Understanding Nirvanix Namespaces

Setting up Nirvanix IFS

Master Accounts

Creating Master Accounts

Child Accounts

Creating Child Accounts

Deleting Child Accounts

Managing Child Account Information

Authentication

Accessing Nirvanix IFS

Creating Directories or Folders

Manipulating Files and Folders

Nirvanix Extensibility

Metadata

Tags

Sharing

Web Services Overview

Calling Nirvanix Web Services (Protocols)

REST

SOAP

HTTP GET (File Retrieval)

Downloading Files

Request URL

Uploading Files

HTTP Upload

Virtual URL Hosting

Managing Virtual URLs

Propagation Times

Mapped Zones

Generating Transfer Paths for Mapped Virtual URLs

Using Web Services with Virtual URLs

Glossary

API Reference Section

Accounting Namespace

CreateChildAccount

DeleteChildAccount

GetAccountUsage

GetAccountLimits

SetAccountLimits

GetAccountInfo

SetAccountInfo

SetAccountStatus

GetAccountNotes

SetAccountNotes

GetStorageUsage

ListChildAccounts

Audio Namespace

Transcode

Authentication Namespace

Login

LoginProxy

Logout

ChangePassword

SetChildAccountPassword

Image Namespace

Resize

RotateFlip

Internet Media File System (IMFS) Namespace

Common IMFS Errors

CopyFiles

CopyFolders

CreateFolders

DeleteFiles

DeleteFolders

GetPathInfo

ListFolder

MoveFiles

MoveFolders

RenameFile

RenameFolder

GetDownloadNodes

GetOptimalUrls

GetStorageNodeExtended

GetStorageNode

SearchFileSystem

Sideload

Metadata Namespace

DeleteAllMetadata

DeleteMetadata

GetMetadata

SetMetadata

DeleteAllTags

DeleteTags

GetTags

SetTags

SearchMetadata

SearchTags

Sharing Namespace

ListHostedItems

CreateHostedItem

RemoveHostedItem

Transfer Namespace

AppendFile (SOAP ONLY)

UploadFile (SOAP ONLY)

Video Namespace

PresetTranscode

Transcode

ExtractFrames

Exception Framework

Appendices

Date Formats

Country Codes for Web Services

SOAP WSDL URLs

Image Conversion Formats

Audio Transcode Formats / Codecs

Video PresetTranscode Formats / Codecs

Document version 2.1

Product version 2.6.2

Related Documentation

See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for an in-depth explanation of more complex topics.

Getting Started: An introduction to key concepts

What is an Internet File System?

An Internet File System (IFS) is an Internet storage service that allows applications to upload, store, and organize files and subsequently access them using a standard Web Services interface. An IFS is a distributed clustered file system, accessed over the Internet, and optimized for dealing with large files (archive, video, research data, etc.) The goal of an IFS is to provide massive scalability to deal with the challenges of storage growth, with guaranteed access and availability regardless of time and location. Finally, an IFS gives applications the ability to access data securely, without the large fixed costs associated with acquiring and maintaining physical storage assets.

An IFS is:

• A file system for the Internet;
• Accessed via Web Services;
• Completely secure and protected;
• Implemented as a cluster of nodes;
• Consumed on-demand, as a service;
• Optimized for managing large files.

When to use the Nirvanix IFS?

Internet File Systems are great solutions for enterprises needing highly scalable, distributed, offsite storage for archiving, distributed content and collaboration, alternative options for near-line data retention, fixed content storage, and video/music/photo management. Instead of building a storage file system from scratch or buying an expensive storage solution, an enterprise can avoid the upfront cost and ongoing maintenance windows by simply connecting to an online storage service.

Software and service providers often want to focus their development and sustaining efforts on the core of their offering, and not have to learn or hire skills in Internet scale media storage, global network delivery, or user account management and security. These core competencies can be leveraged when storage services are provided by the IFS. Another benefit of using the IFS is in cases where there is resource contention associated with IT budgeting and staffing. The IFS model provides a pay-as-you-go pricing model that scales with usage.

At the same time, an IFS is not the best option for serving storage across the internet to I/O intensive applications inside of the data center. These applications require sub-millisecond response times that the Internet is not yet able to support. This characterization is limited to a small group of solutions, like transactional processing systems, access to block storage, 3D rendering or any other intense I/O application. The Nirvanix Storage Delivery Network (SDN) was built and optimized for managing large volumes of content, ease of integration, ease of scalability, and ease of control.

Understanding Nirvanix Namespaces

A namespace is the logical context in which a group of one or more entities might exist. For describing our Web Services, we use namespaces to group related calls or methods. A method defined in a namespace is associated with that namespace by like functionality. The same method could be independently defined in multiple namespaces, that is, the meaning associated with a method defined in one namespace is independent of the same method declared in any other namespace. An example of this would be the Transcode call which is available in the Video and Audio namespaces.

Setting up Nirvanix IFS

There are two types of accounts the Nirvanix SDN, Master Accounts and Child Accounts. The Master account is responsible for payment associated with the use of our services and for management of end-user accounts. Master accounts are intended for our customers, who build and integrate their own applications to our services and generally should only need one master account for all their corporate needs. Master accounts can have multiple Applications in them. Applications are just that, specific multi-user applications that our customers can use to connect to our services. Within applications, child accounts are aggregated. Each child account has its own usage tracked separately, has its own contact info and can its usage can be limited individually.

Master Accounts

Master accounts can support multiple child accounts. For example, if you were using the Nirvanix IFS to launch a backup service, then you would create a single master account for the service, and then tie each new subscriber to your online backup service into a unique child account. The master account gives the developer an aggregated view into overall usage, while child accounts give developers the ability to segment storage and set strict limits on storage and bandwidth usage limits within these accounts. Master accounts can also have multiple applications (Storage Pools) for multiple services. When you create a new master account through our signup process, the first Application is created for you automatically.

Creating Master Accounts

Master accounts are created and managed via the Nirvanix Management Portal (NMP) through the signup page. This process will let you enter your billing, primary addresses and credit card information. Via the Nirvanix Management Portal, you can also create additional applications (Storage Pools) as desired. This enables developers to have multiple applications tied to and managed underneath a single master account.

Child Accounts

Creating Child Accounts

Child accounts are created via a Web Services call. The CreateChildAccount command can be used to create individually managed end-user accounts underneath an application within a master account. To create a child account, a username and password must be provided. Usernames must be unique within each application. Since our customers control the creation of child accounts for each application, they can decide to give their end-users access to multiple applications by providing the same username and password for every end-user. Similarly, they can have an implementation where each application is separate from the others.

The SetAccountLimits command can be executed when a child account is successfully created. This command allows developers or applications to limit total space and bandwidth consumption for each child account. This feature provides ways to strictly enforce monthly usage limits for subscription or advertising-based services as well as allow offering multiple tiers of storage and bandwidth while pricing accordingly. At any time, you can view the current usage of an account with the GetAccountUsage command described below.

Deleting Child Accounts

The DeleteChildAccount command lets you remove a child account. The account is removed immediately and will not allow login or file system access. The current storage and usage information, such as total download bytes for this child account, will billed at the end of the month to the day you deleted the account. Deleted accounts will no longer be returned when listing child accounts in NMP.

Note: Deleting an account that a Virtual URL is mapped to will delete the Virtual URL.

Managing Child Account Information

SetAccountInfo is a method that allows you to set or change the existing information that is stored about an account.

GetAccountInfo is a method that allows you to extract the contact information for a single child account.

In addition to the contact information the method SetAccountNotes can be used to set per account configuration. This method only accepts valid XML data as parameter. Valid XML data must be formatted in standard XML Format as defined at W3C (http://www.w3.org/TR/2006/REC-xml11-20060816/).

The configuration XML can be used to store detailed account information specific to an account and was designed to be a light data repository for things like notes and other metadata on a child account that is only available to the master account.

Authentication

The authentication system takes in the application key and username/password to authenticate. It returns a session token that will be used for subsequent calls into the system. If you call the login method with a master account you must also provide an application key so it can be determined which application you wish to do file operations on. It is strongly suggested you use a secure socket for connecting your application with the Nirvanix IFS. This will reduce the chances an intermediary party will be able to determine your application key and password. The SessionToken returned will expire if not used within 20 minutes and will be associated with a specific IP address. This timeout is not configurable and is set to enforce a minimum level of security on sessions. Not limited to authentication, all connections are suggested to be done over a secure channel.

As an additional security control, accounts are automatically locked for 15 minutes after 5 failed login attempts. This holds true at both the master and child account levels. If needed, master accounts can be unlocked by customer support before the 15 minute window has elapsed.

Accessing Nirvanix IFS

Creating Directories or Folders

To create a directory you can either upload a file to a path that does not yet exist or call the CreateFolders method passing the entire path you wish to create. If you send a path such as /Folder1/Folder2/Folder3/Folder4 and your current folder structure is:

Folder1
   |_Folder2

Then after the call is executed the new structure will be:

Folder1
   |_Folder2
      |_Folder3
         |_Folder4

Manipulating Files and Folders

With Copy or Move operations you can pass in more than one path for the source. There must be only one destination. If you have a duplicate file or folder going to the destination the entire operation will fail. Any invalid character or paths will result in failure of the entire operation.

The following characters are invalid:

\ / |

In addition, all control characters forbidden by XML 1.0 are also disallowed:

Please see http://www.w3.org/International/questions/qa-controls for more details regarding these forbidden control characters.

Note: slash "/" is reserved as the path delimiter. It cannot be part of a file name or folder name. Also when a file or folder name contains reserved URI characters such as "?" and "&", they must be encoded properly depending on your application's transport.

For more information about how to access files in a child or master account see the the protocols section

back to top

Nirvanix Extensibility

Metadata

Each file can have additional information stored as metadata. This metadata includes height and width for image files, and other secondary information about files that can be retrieved from the file contents. A sample mp3 is listed below to show the format of the metadata XML. Every file contains an base 64 encoded MD5 as part of the Metadata that is generated after the upload is performed. The MD5 metadata cannot be removed or modified.

<Metadata FileName=\"Goodbye Girl.mp3\">
   <Data Key=\"MD5\">Ax53ddeDWw442iOkt==</Data>
   <Data Key=\"Album\">Anthology</Data>
   <Data Key=\"Artist\">Hunter Chordato</Data>

   <Data Key=\"BitRate\">256</Data>
   <Data Key=\"Duration\">263</Data>
   <Data Key=\"Genre\">Soundtrack</Data>

   <Data Key=\"IsVariableBitRate\">0</Data>
   <Data Key=\"Title\">Goodbye Girl</Data>
   <Data Key=\"Track\">5</Data>

</Metadata>

Additional Key/Value pairs can be added or changed using SetMetadata and DeleteMetadata and DeleteAllMetadata.

Tags

Tags allow you to set a list of strings on a particular file or folder. They can be used in a fashion similar to tags in blog posts and are useful for search. The tags can be retrieved using GetTags and they can be set or deleted with SetTags, DeleteTags or DeleteAllTags.

Sharing

Sharing will set one or more folders to be available for viewing by non-authenticated users. This allows functionality such as video streaming and anonymous downloads by anyone who knows the path to the shared items. Any downloads by anonymous users of files that are shared will be applied to your usage and charged as such.

After you have a folder and files uploaded and in your account you can share them using CreateHostedItem. This web service will return the full download link to the file you are sharing or a partial download link if it is a folder. Below is an example of the input and output for the call to allow a shared item. This link will redirect you to the globally load-balanced file. Browsers should automatically support this. If you are writing a download application you will need to support the HTTP 302 Response, as defined in RFC 2616 section 10.3.3 302. When sharing a folder all sub-items (folders and files) are also shared.

Download URL: (Available publicly after success of the call)
http://services.nirvanix.com/AppName/ChildAccount/FolderShared/TestImage.jpg

If you wish to list the items you have previously shared you can call the method ListHostedItems, and then you can call the method RemoveHostedItem to remove any items you no longer wish to share.

Web Services Overview

Web Services can be defined as software designed to support interoperable Machine-to-Machine interaction over a network. Web Services are frequently Web APIs that can be accessed over the Internet and executed on a remote system hosting the requested services. The definition encompasses many different systems, but in common usage and throughout this document the term refers to clients and servers that communicate using XML messages that follow the SOAP or REST standards. Common in both the field and the terminology is the assumption that there is also a machine readable description of the operations supported by the server, often referred to as a Web Services Description Language (WSDL). The latter is not a requirement of SOAP endpoint, but it is a prerequisite for automated client-side code generation in the mainstream Java and .NET SOAP frameworks. Some industry organizations, such as the WS-I, mandate both SOAP and WSDL in their definition of a Web service.

The specifications that define Web Services are intentionally modular, and as a result there is no one document that contains them all. Additionally, there is neither a single, nor a stable set of specifications. There are a few "core" specifications that are supplemented by others as the circumstances and technologies dictate, including:

SOAP: An XML-based, extensible message envelope format, with "bindings" to underlying protocols. The primary protocols are HTTP and HTTPS, although bindings for others, including SMTP and XMPP, have been written.

WSDL: An XML document that allows service interfaces to be described, along with the details of their bindings to specific protocols. Typically used to generate server and client code, and for configuration. This API includes one WSDL document per namespace.

UDDI: A directory service for publishing and discovering metadata about Web Services to enable applications to find Web Services either at design time or runtime. Directory services are not relevant or included in the current implementation of this API.

Most of these core specifications have come from W3C, including XML, SOAP, and WSDL; UDDI comes from OASIS.

Calling Nirvanix Web Services (Protocols)

The SOAP and REST protocols are used for transmission of the data and methods in this document. The SOAP protocol allows for simple integration with most languages and development systems. You can learn more about SOAP at http://en.wikipedia.org/wiki/SOAP. For more information about REST you can visit http://en.wikipedia.org/wiki/Representational_State_Transfer. REST and SOAP methods are available via SSL through HTTPS. As a general practice the REST implementation is more flexible and should be preferred over SOAP when designing your system. See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for advantages and disadvantages.

REST

API Method Request Format: API methods are encapsulated by web pages within the API web site. To call a method, make a POST or GET request to the web page corresponding to the method you want to execute.

The URL format for requests is:
http://services.nirvanix.com/ws/{NameSpace}/MethodName.ashx?name=value&name2=value2

Here is an example URL:
http://services.nirvanix.com/ws/Authentication/Login.ashx?appKey=YOURAPPKEY&username=testuser&password=Abc123

API Method Paths: Many API methods require a "path" parameter. A path represents the folders and files within an account, similar to a windows path or URL path. In general, paths can be specified as either absolute or relative to the accounts root folder. For example, if the caller logged in with application name "GoodApp" and account name "admin" then the following paths are equivalent:

Absolute: //GoodApp/username/path/file.txt
Relative: /path/file.txt

In the case where relative path is absent or null, the accounts root folder is the assumed path.

For most cases, relative paths should be used because it is simpler, easier, and shorter to reference. However, in cases where the caller needs to access another users file system (such as an master account managing a child account), absolute paths must be used.

The API calls that are plural indicate that one or more paths may be provided. Examples of this would be GetOptimalUrls which allows you to get several tokenized URLs in a single call. Singular API calls such as ListFolder operate on a single path at a time. For the most optimal operation the arrays should be passed in at most with 100 paths at a time.

API Method Response Format: When an API method is called, a response is returned to the caller in XML format. The content type of the response will be "text/xml". The default XML response for methods that do not return data to the caller is:

<Response>
  <ResponseCode>0</ResponseCode>
</Response>

A "code" value of zero (code="0") indicates that the method completed successfully. If the code is not zero, then an error occurred and the XML response will look like this:

<Response>
   <ResponseCode>80006</ResponseCode>

   <ErrorMessage>Session not found for ip = 10.0.0.1, token = 2dc8542b-210d-45df-85df-b48b277c13c5
   </ErrorMessage>
</Response>

REST Output Format: All Nirvanix Web Services API responses can be optionally be output in JSON format. JSON (JavaScript Object Notation) is a lightweight data-interchange format. For JavaScript applications, it is a much more efficient format to parse than XML since it is a subset of the JavaScript Programming Language. By default, Nirvanix Web Services API responds in XML format. To enable JSON output format, simply append the query string "output=json" to the URL of any API call except Upload or Download. For example, this API call

/ws/IMFS/ListFolder.ashx?sessionToken=YOURSESSIONTOKEN&folderPath=DirTest/F8&pageNumber=1&pageSize=5&output=json

returns

{
	"ResponseCode":0,
	"ListFolder":{
		"TotalFolderCount":3,
		"TotalFileCount":365, 
		"PageFolderCount":3,
		"PageFileCount":2,
		"Folder":[
			{
				"FolderCount":0,
				"FileCount":1,
				"Name":"FolderA",
				"Path":"DirTest\/F8\/FolderA",
				"CreatedDate":"Wed, 02 May 2007 13:36:41 GMT",
				"Metadata":null,
				"FileTags":null
			},
			{
				"FolderCount":1,
				"FileCount":0,
				"Name":"FolderB",
				"Path":"DirTest\/F8\/FolderB",
				"CreatedDate":"Wed, 02 May 2007 13:36:56 GMT",
				"Metadata":null,
				"FileTags":null
			},
			{
				"FolderCount":1,
				"FileCount":1,
				"Name":"FolderC",
				"Path":"DirTest\/F8\/FolderC",
				"CreatedDate":"Wed, 02 May 2007 13:37:22 GMT",
				"Metadata":null,
				"FileTags":null
			},
		],
		"File":[
			{
				"SizeBytes":1851,
				"Name":"image.png",
				"Path":"DirTest\/F8\/image.png",
				"CreatedDate":"Fri, 11 Jul 2008 15:17:42 GMT",
				"Metadata":
					"<Metadata FileName=\"image.png\">
						<Data Key=\"Width\">167<\/Data>
						<Data Key=\"Height\">85<\/Data>
						<Data Key=\"MD5\">GLGS2vG\/IhfLMnEHOCpuAw==<\/Data>
					<\/Metadata>",
				"FileTags":"these|are|my|tags"
			},
			{
				"SizeBytes":637,
				"Name":"text.txt",
				"Path":"DirTest\/F8\/text.txt",
				"CreatedDate":"Fri, 11 Jul 2008 15:18:29 GMT",
				"Metadata":
					"<Metadata FileName=\"text.txt\">
						<Data Key=\"MD5\"> 5JiKJuJEqUv0Kmr8kadqYw== <\/Data>
					<\/Metadata>",
				"FileTags":null
			}
		]
	}
}

JSON Callbacks: To allow embedding remote JSON in your web page the JSONcallback parameter is available. This will wrap the JSON result in a method name. When included as the source of a script call the JSON will be executed. By having the method that you pass in the JSON in your local page it will be called with the JSON object as the parameter. This avoids having to proxy the JSON result in a page hosted on your domain.

An example of this is:

/ws/Authentication/Login.ashx?appKey=XYZ-YOUR-APPKEY&username=YOURUSER&password=YOURPASSWORD&output=json&JSONcallback=loginresult

returns

loginresult({"ResponseCode":0,"SessionToken":"1cf8ff68-b93f-49a8-a375-5d437324b8fc"});

An example web page might look like:

<html>
	<head>
		<title>Display Session Token</title>
	</head>
	<script type="text/javascript">
	function loginresult(json) {
		alert("Session Token: " + json.SessionToken);
	}
	</script>
	<script type="text/javascript" src="http://services.nirvanix.com/ws/Authentication/
	Login.ashx?appKey=XYZ-YOUR-APPKEY&username=YOURUSER&password=YOURPASSWORD&output=json&
	JSONcallback=loginresult"></script>
	<body>
		This will automatically call the loginresult method displaying the Session Token
		 in an alert.
	</body>
</html>

SOAP

To call our web service your client must be able to consume our WSDL file. Most programming and scripting languages have tools that facilitate consuming a web service. Generally, when your developer toolkit inspects the WSDL file it will auto-generate programming code that interfaces with the Web Services. Nirvanix has individual WSDLs for each namespace.

An example WSDL link for the Authentication namespace is here:

http://services.nirvanix.com/ws/Authentication.asmx?WSDL

When using Visual Studio you can attach to a SOAP WSDL through the "Add Web Reference" interface. This will allow you to create a local object that acts as the remote SOAP interface handling the calls and instantiation for you automatically.

In the appendix you can find all of the SOAP WSDL links.

HTTP GET (File Retrieval)

The download component allows users of the Nirvanix Internet File System (IFS) to retrieve and download their files. For each download request, the download component performs authentication and authorization before actually serving out the bytes. At the end of each request, it also records the actual number of bytes served for accounting purposes including partial file downloads.

Because of the global caching node architecture, downloading a file from IFS is a two-step process. First the user must obtain the download location for each file path from the IFS interface. This will return the optimum download node which has the requested file based on the user's geographical location or SLA. Once this download node is known, the user can simply perform an HTTP get request to download the file from that node.

Once the download node for a file is known, the file can be downloaded by a normal HTTP Get request. The download URL has the following format:
http://<DownloadNode>/<AppName>/<AccountName>/<RelativeFilePath>?sessionToken=<SessionToken>

In the case when the user has granted access of a file to the public, the sessionToken parameter is omitted from the URL.

If the user is authenticated and authorized to download the file, the GET will succeed and the files content will be streamed to the requesting client. After the request ends, the actual number of bytes served will be recorded for accounting purposes. This happens even if the client aborts the download in which case, the number of bytes served up to that point will be recorded.

For additional information on the HTTP GET protocol, see section 9.3 of RFC 2616 for information about GET and partial GET (progressive download).

Downloading Files

See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for further discussion about downloading files, including recommendations for retry and reroute logic.

Request URL

To download a file from the Nirvanix IFS, you can make a REST request to the transfer node using the GET method. The URL has the following format:

http://<Node>/<sessionToken>/<appName>/<userName>/<path>
 

For publicly hosted file, the sessionToken can be omitted:

http://<Node>/<appName>/<userName>/<path>
 

You can also access files using an access token created by the GetOptimalUrls call:

http://<Node>/<downloadtoken>/<appName>/<userName>/<path>
 

Optionally, you can also specify the downloads content disposition with the query parameter "disposition". Valid values for this parameter are "inline" and "attachment". This modifies the returned Content-Disposition header and can allow browsers to be prompted to save the file or show the contents as part of the web page.

To obtain a session token, please see the Login method in the Authentication namespace.

To obtain the transfer node, please see the GetDownloadNodes method in the IFS namespace. As an alternative, and to make this a one-step process, you can also make the same download request to services.nirvanix.com and be redirected to the correct transfer node. This redirection uses a HTTP 302 response with the node specified in the location header.

Request Headers

Nirvanix IFS file download accepts the following standard HTTP request headers:

• If-Modified-Since
• If-None-Match
• Range

Response Headers

Nirvanix IFS file download response includes the following standard HTTP response headers:

• Content-Length
• Content-Type
• Content-Range (if requesting range)
• Content-Disposition (if specified in the request)
• Last-Modified
• ETag

Uploading Files

For optimal performance, the process to upload files is a 2-step process, where the Upload node is first identified by the method GetStorageNode or GetStorageNodeExtended, followed by the upload to that particular node. The upload token and upload servers IP address are retrieved by GetStorageNode. The Upload Token will expire (default is 10 minutes for first byte, 72 hours for last byte) and is not refreshed. This means the token will expire even if it is being used, unlike the session token. Before each upload you must ask for the upload node and use the information for that upload. Upload tokens should be used only once per file being uploaded so there is no chance of a collision while doing uploads.

See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for more discussion of upload, including recommendations for retry and reroute logic.

HTTP Upload

The HTTP protocol allows a multipart/form-data POST to upload files using "/Upload.ashx". Once the HTTP post is complete the response is a summary of the upload. Optionally the user can be forwarded to another URL after the upload is complete. If the user is forwarded, some additional parameters are appended to the forwarding URL. This allows users to upload directly from a webpage to the Nirvanix IFS. Another option is to specify a callback URL. This URL is invoked when the file has been completely uploaded.

The IFS destination of upload files is <destFolderPath>/<non-common request path-part>/<request file name>

For example if the user uploads the files in a single request using destFolderPath = "MyOnlinePhotos" the following are the resulting destination IFS paths:

When submitting a request with multiple files if one of those files has an error such as a path longer than 512 characters all files will be processed until the failed file. The response will be for the file that failed and no information will be returned for the success cases.

The maximum content size is limited to the maximum content-length in the http request which is: 2097150 kilobytes. If you exceed the maximum value you get a 10001 error.

Input Parameters

Output Values

HTTP Upload either responds with the following XML, or it forwards the response via a URL (see Forwarding URL section below).

REST Response XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
                   <xs:element ref="FilesUploaded" minOccurs="0"/>
                   <xs:element ref="BytesUploaded" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="FilesUploaded">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="BytesUploaded">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
            

Sample REST Request

http://node1.nirvanix.com/Upload.ashx?uploadToken=abcd12345&destFolderPath=mydata/myfile.bin

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
   <FilesUploaded>1</FilesUploaded>
   <BytesUploaded>105450</BytesUploaded>
</Response>

Errors

Forwarding URL

If a forwardingURL is passed it must contain a valid query string. It can optionally include the forwarding protocol. When not included the protocol defaults to HTTP. Users are responsible for URL encoding this parameter. See http://www.blooberry.com/indexdot/html/topics/urlencoding.htm for reserved characters that are important for users to encode. For a sample of how to URL encode see http://www.w3schools.com/tags/ref_urlencode.asp.

The fowardingUrl is appended with the following parameters:
NVX.returnCode an integer representing the status of the upload. Did it fail? Success? Valid response codes: see standard return codes; return code 0 means no error.
NVX.errorMessage a string describing the error message associated with any error being returned.

Any parameters provided in the request will also be included in the output. This can be useful for passing the filename and other information that the landing location may need to handle processing the upload.

Callback URL

Users are responsible for URL encoding this parameter. See http://www.blooberry.com/indexdot/html/topics/urlencoding.htm for reserved characters that are important for users to encode. For a sample of how to URL encode see http://www.w3schools.com/tags/ref_urlencode.asp.

The callbackURL is appended with the following parameters:
NVX.returnCode an integer representing the status of the upload. Did it fail? Success? Valid response codes: see standard return codes; return code 0 means no error.
NVX.errorMessage a string describing the error message associated with any error being returned.
NVX.absolutePath a string describing the absolute path of the file that was uploaded.
NVX.sizeBytes a long describing the size in bytes of the file that was uploaded.

Any parameters provided in the request will also be included in the output. This can be useful for passing the filename and other information that the landing location may need to handle processing the upload. This is often used to update external databases that keep track of paths within Nirvanix for websites.

Web Browser Uploads

When submitting a request with multiple files, if one of those files has an error such as a path longer than 512 characters all files will be processed in order until the failed file. The response will be for the file that failed and no information will be returned for the success cases. The rest of the request will be discarded.

This allows users to upload directly from a webpage to the Nirvanix IFS.

Below is a simple example of a HTML form that can upload through the HTTP protocol. The "nodex.nirvanix.com" and "UPLOADTOKEN" should be replaced with the values returned from the GetStorageNode API call.

A question that often comes up is the size of the download passed to the GetStorageNode and GetStorageNodeExtended when using a web client to upload. In these instances you will not know the size ahead of time and should instead use the best guess for the file size such as the average file size for you.

<html>
<body>
    <form ENCTYPE="multipart/form-data" action="http://nodex.nirvanix.com/Upload.ashx" method="post">

        <input type="hidden" name="uploadToken" value="UPLOADTOKEN" /><br />
        Upload Folder: <input type="text" name="destFolderPath" /><br />
	Metadata 1: <input type="text" name="metadata" /><br />
        File 1: <input type="file" name="uploadFile1"/><br />
	Metadata 2: <input type="text" name="metadata" /><br />
        File 2: <input type="file" name="uploadFile2"/><br />

        <input type="submit" value="Upload"/>
    </form>
</body>
</html>

Custom Http Uploading

The http protocol allows a multipart/form-data POST (RFC 1867) to upload files using "/Upload.ashx". You can pass two required parameters "uploadToken" and "destFolderPath" in the form data. These must precede any multipart form data which contains file content. This allows us to verify security before attempting to accept the upload, if this is not done you will receive an error.

You may upload multiple files in one form if all the file data for each file fits in that form. When a file spans multiple forms (Partial File Upload) by incrementing the Content-Range value in each form sent, you must specify only one file per form.

The maximum content size is limited to the maximum content-length in the http request which is: 2,097,150 kilobytes. If you exceed the maximum value you get a 10001 error.

To handle the multipart/form-data post directly you can use libraries such as Curl or other direct writes to the HTTP headers. This allows you to do uploads outside of the browser and stream the data you wish to upload directly to the Nirvanix servers. A sample HTTP request's content is provided below as an example.

-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="uploadToken"\r\n
\r\n
fe-pC9v9~pRYkzGkBHQ~STJX0Ac2~48J3zyLxVO~APDbYlYSk5JO8xFTZw\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="destFolderPath"\r\n
\r\n
/backup\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="forwardingURL"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackURL"\r\n
\r\n
http://myserver.com/Callback.aspx?NVX.returnCode=0&NVX.absolutePath=
//MyApp/Myaccount/myfolder/myfile.jpg&NVX.sizeBytes=1024\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="fileContent"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 0-4/5\r\n
Content-MD5: zie0mjZg+7Gf65HcHSJ/QQ==\r\n
Content-Metadata: type1:value1,type2:value2
\r\n
0xf0 0xf1 0xf2 0xf3 0xf4\r\n
-----------------------------170062046428149--\r\n

Each form data part is separated by a boundary. In the example above, this boundary appears as "-----------------------------170062046428149". This is a unique value that must not appear in the data. The \r\n throughout the form data represents carriage return/linefeed characters that is used as the separator for lines in a POST of the multipart/form-data. Each form data part begins with the header information for that part followed by the content of that part which may be the value of an input parameter of the form or the content of a file. A blank line delimits the header from the content. More information on HTTP Headers can be found in RFC 2616 Section 14.

The HTTP headers of parts containing file content includes the following:

• Content-Disposition - Defines the file name
• Content-Type - Defines the type of file being uploaded. Binary/octet-stream is generic binary data and can be used for all file types.
• Content-Range (Optional) - Lets you define portions of the file to upload. The format is firstBytePosition-lastBytePosition/totalFileLength where the byte positions are zero-based.
• Content-MD5 (Optional) - See Input Parameters section above.
• Content-Metadata (Optional) - See Input Parameters section above.

Content-Range

The Content-Range header is sent with a partial part of a file to specify where in the full file the partial part should be applied (RFC2616 Section 14.16). It is used to allow two different upload actions.

Partial File Upload

When included with a HTTP upload (/Upload.ashx), it will allow you to upload contiguous portions of a file in multiple requests by providing the range that you will be sending in each request. This allows you to upload extremely large files (file size greater than 2 GB which is the limit of a single HTTP request) by progressively appending content of a file spanning multiple requests rather than sending the entire file in one request. In this case, the Content-Range must adhere to the following guidelines or an error will be returned:

• The first byte position of the very first range must be 0.
• For each subsequent range, the first byte position must be 1 more than the last byte position of the preceding range. You must append the content of the file in order, not randomly.
• The last byte position of the last range must be 1 less than the total file length (since byte position is zero-based.) This signals that the entire file has been uploaded.
• If Content-Range is not provided, it is assumed the entire file will be uploaded in a single request.

back to top

Virtual URLs

Virtual URLs allow the use of a customer's own domain or sub-domain to be used as a mask over Nirvanix URLs when making download or operational calls. This is done through a two step process of registering the desired name with Nirvanix using the Nirvanix Management Portal (NMP), and then creating the necessary CNAME records to allow for proper name resolution.

For example, if a customer controls the domain "MyCompany123.com" and would like to use the sub-domain "storage.MyCompany123.com" for all SDN calls, they can simply register the sub-domain in NMP and then create CNAME entries for:

• services.storage.MyCompany123.com
• nodeX.storage.MyCompany123.com - "X" must be replaced with a numeric value for all the nodes in the Nirvanix SDN; details for this are provided in NMP

Once the CNAME entries are propagated, the customer-defined sub-domains can be used in place of the usual Nirvanix sub-domains.

A Nirvanix customer can optionally map a Virtual URL to an existing Application that they manage, or a single Account beneath such an application. A Virtual URL that is mapped to an Application or Account is granted default and restricted access to that Application or Account.

Notes:

• A Virtual URL can only have one mapping. However, a single Application or Account can have several Virtual URLs mapped to it.

Managing Virtual URLs

To use a Virtual URL, the domain or sub-domain must be registered with Nirvanix through NMP. This is required to help prevent URL spoofing.

To do this, login to NMP and browse to the Virtual URLs section under Applications. This page provides all the tools needed to register and customize a Virtual URL with Nirvanix. There you will be presented with the following:

1. A form to create new Virtual URLs.
2. A list of existing Virtual URLs that can be deleted, or have their mappings reassigned.

Propagation Times

A Virtual URL creation, change, or deletion in NMP may take 5 - 10 minutes to fully propagate to the SDN.

CNAME creations, changes, or deletions generally require 24 - 72 hours for the DNS to propagate completely.

Mapped Zones

All Virtual URLs have some sort of mapping. There are three types of mapping allowed:

1. Default Mapping - No specific mapping is designated. Use of this Virtual URL is limited to all Accounts of Applications which are owned by the Master Account that registered the Virtual URL.
2. Application Mapping - The Virtual URL is mapped to a single Application of the Master Account that registered the Virtual URL. Only children of the mapped Application can use this URL.
3. Account Mapping - The Virtual URL is mapped to a single Account of an Application of the Master Account that registered the Virtual URL. Only the mapped Account can use the URL. This is helpful for sharing publicly hosted files.

*Note: Deleting an Application or Account that has Virtual URLs mapped to it will delete the Virtual URL and you will need to re-create them.

Generating Transfer Paths for Mapped Virtual URLs

The main benefit to mapping a Virtual URL is the ability to customize the access paths to get to individual files. Without mapping, Nirvanix file paths take this form:
services.nirvanix.com/<Application Name>/<Account Username>/Path to File

A default download link for a hosted file may look like this:
http://services.nirvanix.com/App_Name/Account_Username/file_in_the_root_directory.txt

However, if a customer has the Virtual URL "storage.MyCompany123.com"mapped to an Application, that Application name should not be included in the URL. The following is a sample URL with Application Mapping:
http://services.storage.MyCompany123.com/Account_Username/File_in_the_root_directory.txt

Similarly, if a customer has the Virtual URL"storage.MyCompany123.com" mapped to an Account, the Application Name and Account Username would not be included. The following is a sample URL with this type of mapping:
http://services.storage.MyCompany123.com/File_in_the_root_directory.txt

Here are the rules for creating Upload and Download paths:

1. Default Mapping - No part of the path is filled in.
2. Application Mapping - The name of the Application that the Virtual URL is mapped to is ALWAYS added to the beginning of the path that is provided.
3. Account Mapping - The name of the Application and the username of the Account that the Virtual URL is mapped to is ALWAYS added to the beginning of the path that is provided.

The GetOptimalUrls Web Service can be used to generate a complete download URL which takes advantage of any Virtual URL mapping. Simply make the call to the GetOptimalUrls web method using the Virtual URL, and response back will be formatted correctly with the same Virtual URL used.

*Note: When using a Virtual URL that has Application Mapping, the Application name must not be included in any upload or download links. When using a Virtual URL mapped to an Account, the Application name and Account username must not be included in any upload or download links. Doing either one of these will result in a "Path Not Found" exception.

Using Web Services with Virtual URLs

All Web services actions are fully supported using Virtual URLs, using either the SOAP or REST protocol. There are no changes to the Web Services Interface. Mappings are enforced at login to provide a secure environment.

For example, a customer has the following:

• The following Applications: App1 and App2
• The Virtual URL "storage.MyCompany123.com" mapped to application App1
• An account of App1 with the username "ChildUser1"
• An account of App2 with the username "Child User of Unmapped App"

The customer can use the following URL to login "ChildUser1":
http://services.storage.MyCompany123.com/ws/Authentication/Login.ashx

However "Child User of Unmapped App" cannot log in using the Virtual URL, because that Account does not belong to the Application that is mapped to the Virtual URL. "Child User of Unmapped App" can continue to use the following URL to perform all Web Services calls: http://services.nirvanix.com/ws/Authentication/Login.ashx

These restrictions are enforced to prevent unauthorized accounts from spoofing Virtual URLs.

*Note: When providing paths for IFS operations, the paths are used as provided, with no regards to Virtual URL Mapping. While Mapped Applications and/or Account Usernames are pre-pended to Transfer links, they are NOT pre-pended to Web Services paths. All paths used through web services are used as-is.

Glossary

CNAME - An alias within a DNS referencing a (sub) domain to a separate (sub) domain’s IP address associations. For example, mapping "node1.storage.MyCompany123.com" to "node1.nirvanix.com".

Default Mapping - A domain (e.g. "MyCompany123.com") or sub-domain (e.g. "storage.MyCompany123.com") that has not been mapped to a specific Application or Child Account but is registered in NMP. For example "storage.MyCompany123.com" pointing to "nirvanix.com".

Mapped Zone - A domain (e.g. "MyCompany123.com") or sub-domain (e.g. "storage.MyCompany123.com") that has been mapped to a specific Application or Child Account within the Nirvanix SDN. For example, "storage.MyCompany123.com" pointing to "nirvanix.com/App1/ChildUser1".

back to top

API Reference Section

Accounting Namespace

The Accounting Namespace allows users to set and retrieve the limits, contact information, and usage for accounts. These settings control the access to a users files. This component exposes the commands that allow a master account to create child accounts, and set and read their limits.

CreateChildAccount

The CreateChildAccount command creates a child account with the provided username, password, and contact information under a specific Application Key. The provided Session Token must be from the login of the master account. The username must be unique under the Application Key associated with the session token.

Input Parameters

Output Values

A ResponseCode is always returned and if successful is a "0". If an error occurs, the ErrorMessage text is also returned.

REST Response XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/CreateChildAccount.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser&password=childpass

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs CreateChildAccount.

back to top

DeleteChildAccount

The DeleteChildAccount command deletes the child account that matches the provided username. The provided Session Token must be from the login of the master account and the Application Key provided must be from an application owned by that master account. The username must be under the Application Key associated with the session token. If the username exists under the Application Key, it will be deleted. A Response Code will be returned.

Note: Deleting an account that a Virtual URL is mapped to will delete the Virtual URL and all files in that account.

Input Parameters

Output Values

A ResponseCode is always returned and if successful is a "0". If an error occurs, ErrorMessage is also returned.

REST Response XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/DeleteChildAccount.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs DeleteChildAccount.

back to top

SetAccountStatus

The SetAccountStatus command allows a child account to be locked or unlocked. The provided Session Token must be from the login of the master account and the Application Key provided must be from an application owned by that master account. The username must be under the Application Key associated with the session token. If the username exists under the Application Key, the status will be modified. A Response Code will be returned.

Input Parameters

Output Values

A ResponseCode is always returned and if successful is a "0". If an error occurs, ErrorMessage is also returned.

REST Response XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/SetAccountStatus.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser&accountStatus=Lock

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs SetAccountStatus.

back to top

GetAccountUsage

The GetAccountUsage command returns all of the usage metrics for the provided username under the provided Application Key. A Response Code will be returned, as well as a list of usage. The usage returned is based on the creation date of the username you are requesting. Every 30 days the account information is reset back to 0 with the exception of the Total Storage Usage which is a running average of current storage. The 30 day reset is inclusive of the 30th day and the limits are actually reset at the beginning of the 31st day.

Available Features returned in the usage results:

• Download Bandwidth Usage
• Upload Bandwidth Usage
• Total Storage Usage

Input Parameters

Output Values

A ResponseCode is always returned and if successful is a "0". A successful execution will return the feature name and usage amount. If an error occurs, ErrorMessage is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>

              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>

                   <xs:element ref="FeatureName" minOccurs="0"/>
                   <xs:element ref="TotalUsageAmount" minOccurs="0"/>
                   <xs:element ref="UsageStartDate" minOccurs="0"/>

                   <xs:element ref="UsageEndDate" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
     <xs:element ref="FeatureName" minOccurs="0"/>
     <xs:element ref="TotalUsageAmount" minOccurs="0"/>

     <xs:element ref="UsageStartDate" minOccurs="0"/>
     <xs:element ref="UsageEndDate" minOccurs="0"/>
</xs:schema>

Sample REST Request

/ws/Accounting/GetAccountUsage.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
	<ResponseCode>0</ResponseCode>
	<GetUsage>
		<FeatureName>Download Bandwidth Usage</FeatureName>
		<TotalUsageAmount>1490048</TotalUsageAmount>
		<UsageStartDate>Sun, 14 Jun 2009 00:00:00 GMT</UsageStartDate>
		<UsageEndDate>Tue, 14 Jul 2009 22:08:24 GMT</UsageEndDate>

	</GetUsage>
	<GetUsage>
		<FeatureName>Total Storage Usage</FeatureName>
		<TotalUsageAmount>726181</TotalUsageAmount>
		<UsageStartDate>Sun, 14 Jun 2009 00:00:00 GMT</UsageStartDate>
		<UsageEndDate>Tue, 14 Jul 2009 22:08:24 GMT</UsageEndDate>
	</GetUsage>

	<GetUsage>
		<FeatureName>Upload Bandwidth Usage</FeatureName>
		<TotalUsageAmount>0</TotalUsageAmount>
		<UsageStartDate>Sun, 14 Jun 2009 00:00:00 GMT</UsageStartDate>
		<UsageEndDate>Tue, 14 Jul 2009 22:08:24 GMT</UsageEndDate>
	</GetUsage>
</Response>

Errors

See code samples using our SDKs GetAccountUsage.

back to top

GetAccountLimits

The GetAccountLimits command returns all of limits for the account associated with the session token. A Response Code will be returned, as well as a list of the limits. The limit will be returned as "-1" if the specified limit is not set. The IsAppKeyLimit defines if a limit has been set on the entire application rather than just at the account.

Available limits returned in the results:

• StorageAmount - The total bytes stored.
• DownloadBandwidthAmount - The total number of bytes that can be downloaded per pay period.
• FileSizeDownloadLimit - The maximum size in bytes of a file that can be downloaded.
• UploadBandwidthAmount - The total number of bytes that can be uploaded per pay period.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return the feature type, feature value, and whether or not the feature limit was associated with an application key. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage " minOccurs="0"/>
                   <xs:element ref="Type" minOccurs="0"/>
                   <xs:element ref="Value" minOccurs="0"/>
                   <xs:element ref="IsAppKeyLimit" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element ref="ErrorMessage " minOccurs="0"/>
     <xs:element ref="Type" minOccurs="0"/>
     <xs:element ref="Value" minOccurs="0"/>

     <xs:element ref="IsAppKeyLimit" minOccurs="0"/>
</xs:schema>

Sample REST Request

/ws/Accounting/GetAccountLimits.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
	<ResponseCode>0</ResponseCode>
	<Limits>
		<Type>StorageAmount</Type>
		<Value>100000</Value>
		<IsAppKeyLimit>false</IsAppKeyLimit>
	</Limits>

	<Limits>
		<Type>DownloadBandwidthAmount</Type>
		<Value>10000</Value>
		<IsAppKeyLimit>false</IsAppKeyLimit>
	</Limits>
	<Limits>
		<Type>FileSizeDownloadLimit</Type>

		<Value>-1</Value>
		<IsAppKeyLimit>true</IsAppKeyLimit>
	</Limits>
	<Limits>
		<Type>UploadBandwidthAmount</Type>
		<Value>-1</Value>
		<IsAppKeyLimit>true</IsAppKeyLimit>
	</Limits>
</Response>

Errors

See code samples using our SDKs GetAccountLimits.

back to top

SetAccountLimits

The SetAccountLimits command sets the limits for the provided username under the provided Application Key. The Session Token must belong to a master Account for the username. All limits are set in bytes and a -1 is used to mark it as unlimited.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">

         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>

              </xs:sequence>
         </xs:complexType>
     </xs:element>
     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />

         </xs:simpleType>
     </xs:element>
     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/SetAccountLimits.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser&StorageAmount=10000&FileSizeDownloadLimit=5000

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs SetAccountLimits.

back to top

GetAccountInfo

The GetAccountInfo command gets the account details for the account associated with the session token. If the session token being used belongs to the master account a child account can be specified in username. If the session token is from a login of a child account then only that child accounts account info can be retrieved.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return account contact data. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="Response">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="ResponseCode" minOccurs="1"/>
                <xs:element ref="ErrorMessage" minOccurs="0"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="GetAccountInfo">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Contact">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element ref="FirstName" minOccurs="0"/>

                            <xs:element ref="LastName" minOccurs="0"/>
                            <xs:element ref="MiddleInitial" minOccurs="0"/>
                            <xs:element ref="PhoneNumber" minOccurs="0"/>

                            <xs:element ref="EmailAddress" minOccurs="0"/>
                            <xs:element ref="EmailFormat" minOccurs="0"/>
                            <xs:element ref="AddressLine1" minOccurs="0"/>

                            <xs:element ref="AddressLine2" minOccurs="0"/>
                            <xs:element ref="City" minOccurs="0"/>
                            <xs:element ref="State" minOccurs="0"/>

                            <xs:element ref="CountryID" minOccurs="0"/>
                            <xs:element ref="PostalCode" minOccurs="0"/>
                      </xs:sequence>
                 </xs:complexType>
             </xs:element>
             <xs:element ref="UserName" minOccurs="0"/>
             </xs:sequence>
         </xs:complexType>
     </xs:element>
        
     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element ref="ErrorMessage" type="xs:string"/>
     <xs:element ref="UserName" type="xs:string"/>

     <xs:element ref="FirstName" type="xs:string"/>
     <xs:element ref="LastName" type="xs:string"/>
     <xs:element ref="MiddleInitial" type="xs:string"/>

     <xs:element ref="PhoneNumber" type="xs:string"/>
     <xs:element ref="EmailAddress" type="xs:string"/>
     <xs:element ref="EmailFormat" type="xs:string"/>

     <xs:element ref="AddressLine1" type="xs:string"/>
     <xs:element ref="AddressLine2" type="xs:string"/>
     <xs:element ref="City" type="xs:string"/>

     <xs:element ref="State" type="xs:string"/>
     <xs:element ref="CountryID">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element ref="PostalCode" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/GetAccountInfo.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser&ContactType=TechnicalContact

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
	<ResponseCode>0</ResponseCode>
	<GetAccountInfo>
		<Contact>
			<FirstName>First</FirstName>
			<LastName>Last</LastName>
			<MiddleInitial>M</MiddleInitial>
			<PhoneNumber>123-123-1234</PhoneNumber>
			<EmailAddress>me@here.now</EmailAddress>
			<EmailFormat>Text</EmailFormat>
			<AddressLine1>123 here st.</AddressLine1>
			<AddressLine2>Unit 11</AddressLine2>
			<City>Good City</City>
			<State>CA</State>
			<CountryID>1</CountryID>
			<PostalCode>12345</PostalCode>
		</Contact>
		<Username>mychilduser</Username>
	</GetAccountInfo>
</Response>
					

Errors

See code samples using our SDKs GetAccountInfo.

back to top

SetAccountInfo

The SetAccountInfo command changes the account details for the provided username. To set the account information for a child account you must use a session token from the master account for that child or from the login of the child itself.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">

         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>

              </xs:sequence>
         </xs:complexType>
     </xs:element>
     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />

         </xs:simpleType>
     </xs:element>
     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/SetAccountInfo.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser&firstName=First&lastName=Last&middleInitial=M&phoneNumber=123-123-1234&
emailAddress=me@here.now&emailFormat=html&address1=123 Here St.&address2=Unit 11&city=Good City&
State=CA&CountryID=1&PostalCode=12345&ContactType=TechnicalContact

Sample REST XML Response

						
<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
</Response>
					

Errors

See code samples using our SDKs SetAccountInfo.

back to top

SetAccountNotes

The SetAccountNotes command sets an XML document stored with the account. The XML must be well formed or it will be rejected. The Session Token must belong to a master Account for the username.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/SetAccountNotes.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser&xmlNotes=<xml><note1>Test</note1></xml>

Sample REST XML Response

						
<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
</Response>
					

Errors

See code samples using our SDKs SetAccountNotes.

back to top

GetAccountNotes

The GetAccountNotes command retrieves an XML document stored with the account. This method can only be called by the master account. The standard usage is to provide notes about a child account that are not visible to that child. An XML document will be returned.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>

              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="xmlNotes" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="xmlNotes" type="xs:string"/>
     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/GetAccountNotes.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser

Sample REST XML Response

						
<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
   <GetAccountNotes><xml><note1>test</note1></xml></GetAccountNotes>
</Response>
					

Errors

See code samples using our SDKs GetAccountNotes.

back to top

GetStorageUsage

The GetStorageUsage command returns the total storage usage for the account passed in the username. A Response Code will be returned, as well as the total storage in bytes. This can be called by either the master or child account but one child account cannot view another.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return the total storage in bytes. If an error occurred, an Error Message is returned.

REST XSD

	
<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
                   <xs:element ref="StorageUsage" minOccurs="0"/>
              </xs:sequence>

         </xs:complexType>
     </xs:element>
     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />

         </xs:simpleType>
     </xs:element>
     <xs:element ref="ErrorMessage" minOccurs="0"/>
     <xs:element name="StorageUsage">

         <xs:simpleType>
              <xs:restriction base="xs:long" />
         </xs:simpleType>
     </xs:element>
</xs:schema>

Sample REST Request

/ws/Accounting/GetStorageUsage.ashx?sessionToken=YOURSESSIONTOKEN
&username=mychilduser

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
	<StorageUsage>12345678</StorageUsage>
</Response>

Errors

See code samples using our SDKs GetStorageUsage.

back to top

ListChildAccounts

The ListChildAccounts method will retrieve the list of child accounts associated with the specified master account under the current storage pool. This method can only be called by the master account.

Input Parameters

Output Values

A Response Code is always returned. A pages of child accounts will be returned based on the pageSize and pageNumber. If an error occurred, an Error Message is returned.

	
<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
                   <xs:element ref="Account" minOccurs="0" maxOccurs="500"/>
              </xs:sequence>

         </xs:complexType>
     </xs:element>
     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />

         </xs:simpleType>
     </xs:element>
     <xs:element ref="ErrorMessage" minOccurs="0"/>
     <xs:element name="Account" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Accounting/ListChildAccounts.ashx?sessionToken=YOURSESSIONTOKEN
&pageNumber=1&pageSize=500

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
	<Account>childuser1</Account>
	<Account>childuser2</Account>
</Response>

Errors

See code samples using our SDKs ListChildAccounts.

back to top

Audio Namespace

The Audio Namespace allows a user to convert an audio file from one format to another with the ability to specify optional parameters such as number of frames, frame rate, and number of audio channels.

Transcode

The Transcode method is used to convert an audio file from one format to another.

Input Parameters

Output Values

A result code with the status of the transcode command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual transcode operation was successful.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>

                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Audio/Transcode.ashx?sessionToken=YOURSESSIONTOKEN
&srcFilePath=mysong.mp3&destFilePath=mynewsong.wav&numberOfFrames=10000&bitRate=192000
&callbackURL=http://www.yoursite.com/callbackhandler.php

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Callback Response

When provided a callback will be made to a web server you have defined. The request will be made with a HTTP GET.

http://www.yoursite.com/callbackhandler.php?NVX.returnCode=00000
&NVX.errorMessage=Error Message for Audio Transcode.

Errors

See code samples using our SDKs Audio Transcode.

back to top

Authentication Namespace

The Authentication namespace is used to allow connections into the system. Every connection must first retrieve a session token from the login method. This will allow you to authenticate using a single accounts username and password under a single application.

Login

The Login method is used to login to the system and generate a Session Token restricted to the caller's IP address.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
                   <xs:element ref="SessionToken" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
     <xs:element name="SessionToken" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Authentication/Login.ashx?appKey=YOURAPPKEY&userName=testuser&password=Abc123

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
	<SessionToken>6dfa5a15-a4e1-4e9a-9c0e-0cf4299936af</SessionToken>
</Response>

Errors

See code samples using our SDKs Login.

back to top

LoginProxy

The LoginProxy method is used to login to the system on behalf of another consumer and generate a Session Token restricted to that consumer's IP address.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
                   <xs:element ref="SessionToken" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
     <xs:element name="SessionToken" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Authentication/LoginProxy.ashx?appKey=YOURAPPKEY&userName=testuser
&password=Abc123&consumerIP=123.123.123.123

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
	<SessionToken>6dfa5a15-a4e1-4e9a-9c0e-0cf4299936af</SessionToken>
</Response>

Errors

See code samples using our SDKs LoginProxy.

back to top

Logout

The Logout method removes a session token from use. This is primarily used for security so when you are finished with a session token it cannot be used by anyone else. This will also allow you to switch the session token when combined with the login if the account is in continuous use such as a background processing application.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Authentication/Logout.ashx?sessionToken=YOURSESSIONTOKEN

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs Logout.

back to top

ChangePassword

The ChangePassword is used to change an accounts own password.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Authentication/ChangePassword.ashx?appKey=YOURAPPKEY
&userName=testuser&oldPassword=Abc123&newPassword=Def456

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs ChangePassword.

back to top

SetChildAccountPassword

The SetChildAccountPassword is used by a master account to set a child accounts password.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Authentication/SetChildAccountPassword.ashx?appKey=YOURAPPKEY
&userName=MasterUser&password=Abc123&childAccountUsername=testuser&childAccountPassword=Def456

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs SetChildAccountPassword.

back to top

Image Namespace

For Nirvanix Web Services 1.0 the Image component currently consists of taking an image in your file system and resizing it. This is useful, for example, in resizing images dynamically for displaying on different device-types, or rendering display thumbnails of large images uploaded by users.

Resize

The Resize method is used to resize an existing image. A new image will be created as a result and put into your file system.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned. A callback will be made when the resize is completed or has an error.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Image/Resize.ashx?sessionToken=YOURSESSIONTOKEN&srcFilePath=
Folder/subfolder/samplefile.jpg&destFilePath=MyResizedImages/samplefileResized.gif
&width=320&height=640&callbackURL=http://www.yousite.com/callbackhandler.php

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Callback Response

When provided a callback will be made to a web server you have defined. The request will be made with a HTTP GET.

http://www.yoursite.com/callbackhandler.php?NVX.returnCode=00000
&NVX.errorMessage=Error Message for Image Resize.

Errors

See code samples using our SDKs Image Resize.

back to top

RotateFlip

The RotateFlip method is used to rotate or flip an existing image. A new image will be created as a result and put into your file system.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned. A callback will be made when the RotateFlip is completed or has an error.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Image/RotateFlip.ashx?sessionToken=YOURSESSIONTOKEN&srcFilePath=
Folder/subfolder/samplefile.jpg&destFilePath=MyNewImages/samplefileRotated.gif
&rotate=Rotate90&flip=FlipHorizontal&callbackURL=http://www.yoursite.com/callbackhandler.php

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Callback Response

When provided a callback will be made to a web server you have defined. The request will be made with a HTTP GET.

http://www.yoursite.com/callbackhandler.php?NVX.returnCode=00000
&NVX.errorMessage=Error Message for Image RotateFlip.

Errors

See code samples using our SDKs Image RotateFlip.

back to top

Internet File System (IFS) Namespace

All file system operations require the caller to be authenticated. Therefore, all IFS calls require a session token which can be obtained by the Login call. In general, paths can be specified as either absolute or relative to the accounts root folder. For example, if the caller logged in with application key "12345678-ABCD-1234-1234-ABCD12345678" and account name "admin" then the following paths are equivalent:

In the case where relative path is absent or null, the accounts root folder is the assumed path.

For most cases, relative paths should be used because it is simpler, easier, and shorter to reference. However, in cases where the caller needs to access another users file system (such as an administrator managing a user's account), absolute paths must be used.

All IFS calls may potentially result in a set of common errors. The following table lists these common errors. Each IMFS method may also define additional errors specific to that call.

Common IMFS Errors

The following are the Web Service interfaces for IMFS.

CopyFiles

The CopyFiles method is used to copy a file from one location to another. The CopyFiles method can be used to copy one or more files to a given folder. When files are copied, all metadata associated with the original file is also associated with the copied file.

CopyFiles is asynchronous, so a success response does not mean the copy has completed. There is no good way to determine when a copy has completed. Subsequent commands that access the source or destination of the copy before it completes will fail with 70026 File Locked, 70027 Folder Locked, or 70005 Invalid Path. These commands are: Upload (overwrite existing file), RenameFiles, RenameFolders, MoveFiles, MoveFolders, CopyFiles, CopyFolders, DeleteFiles, DeleteFolders. The solution is using retry logic for the 3 errors on each of these commands. Retry logic has the potential to be extremely abusive to the SDN if not done correctly (i.e. retrying in tight loop forever with no sleeps). To be nice, you need to use incremental increasing sleep time between retries (e.g, 1, 2, 4, 8... to max of 60 seconds). The initial sleep time should be roughly based on how large your copy operation is.

The maximum size for any path is 512 characters. If a file is copied into a folder and the resulting file path is more that 512 characters long, the file will become unusable. Any attempt to access or rename this file, or list the contents of the parent folder will result in the following error: 70009 - Path is longer than the maximum allowable length of 512.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/CopyFiles.ashx?sessionToken=YOURSESSIONTOKEN
&srcFilePath=Folder/subfolder/samplefile.txt&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs CopyFiles.

back to top

CopyFolders

The CopyFolders method is used to copy a folder from one location to another. The CopyFolders method can be used to copy one or more folders. Any file that resides within folders that are copied and has metadata associated with it will also have that same metadata associated with the copied files.

CopyFolders is asynchronous, so a success response does not mean the copy has completed. There is no good way to determine when a copy has completed. Subsequent commands that access the source or destination of the copy before it completes will fail with 70026 File Locked, 70027 Folder Locked, or 70005 Invalid Path. These commands are: Upload (overwrite existing file), RenameFiles, RenameFolders, MoveFiles, MoveFolders, CopyFiles, CopyFolders, DeleteFiles, DeleteFolders. The solution is using retry logic for the 3 errors on each of these commands. Retry logic has the potential to be extremely abusive to the SDN if not done correctly (i.e. retrying in tight loop forever with no sleeps). To be nice, you need to use incremental increasing sleep time between retries (e.g, 1, 2, 4, 8... to max of 60 seconds). The initial sleep time should be roughly based on how large your copy operation is.

The maximum size for any path is 512 characters. When a folder is copied into another folder any resulting file path that is more that 512 characters long will become unusable. Any attempt to access or rename this file or folder, or list the contents of the parent folder, will result in the following error: 70009 - Path is longer than the maximum allowable length of 512.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/CopyFolders.ashx?sessionToken=YOURSESSIONTOKEN&
srcFolderPath=Folder/subfolder/FolderToCopy&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs CopyFolders.

back to top

CreateFolders

The CreateFolders method is used to create one or more folders at the specified location.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/CreateFolders.ashx?sessionToken=YOURSESSIONTOKEN
&folderPath=Folders/subfolder/NewFolder/1&folderPath=Folders/subfolder/NewFolder2

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs CreateFolders.

back to top

DeleteFiles

The DeleteFiles method is used to remove one or more files. There may be a slight delay after a file is deleted before it unavailable for download.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/DeleteFiles.ashx?sessionToken=YOURSESSIONTOKEN
&filePath=Folders/subfolder/myfile.txt

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs DeleteFiles.

back to top

DeleteFolders

The DeleteFolders method is used to remove one or more folders. Folders will be deleted even if they contain files.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/DeleteFolders.ashx?sessionToken=YOURSESSIONTOKEN
&folderPath=Folders/subfolder

Sample REST XML Response

<Response>
	<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs DeleteFolders.

back to top

GetPathInfo

The GetPathInfo method is used to retrieve information about an existing file or folder. It provides some basic information about the item, such as the file size, whether the path is a file or folder, metadata, tags, created date, and last modification date.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="Response">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="ResponseCode" minOccurs="1"/>
                <xs:element ref="ErrorMessage" minOccurs="0"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="GetPathInfo">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="ItemName" minOccurs="0"/>
                <xs:element ref="IsFile" minOccurs="0"/>
                <xs:element ref="CreatedDate" minOccurs="0"/>
                <xs:element ref="SizeBytes" minOccurs="0"/>
                <xs:element ref="FileType" minOccurs="0"/>
                <xs:element name="MetaData">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element ref="Data" minOccurs="0"/>
                      </xs:sequence>
                 </xs:complexType>
                 </xs:element>
                 <xs:element ref="Tags" minOccurs="0"/>
                 <xs:element ref="IsShared" minOccurs="0"/>
                 <xs:element ref="ModifiedDate" minOccurs="0"/>
                 <xs:element ref="ItemID" minOccurs="0"/>
             </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element ref="ItemName" type="xs:string"/>
     <xs:element ref="IsFile" type="xs:boolean"/>

     <xs:element ref="CreatedDate" type="xs:string"/>
     <xs:element ref="SizeBytes">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>
     <xs:element ref="FileType" type="xs:string"/>

     <xs:element ref="Data" type="xs:string"/>
     <xs:element ref="Tags" type="xs:string"/>
     <xs:element ref="IsShared" type="xs:boolean"/>

     <xs:element ref="ModifiedDate" type="xs:string"/>
     <xs:element ref="ItemID" type="xs:string"/>

</xs:schema>

Sample REST Request

/ws/IMFS/GetPathInfo.ashx?sessionToken=YOURSESSIONTOKEN
&itemPath=DirTest/F8.jpg&showMetadata=true&showTags=false&showIsShared=true

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
	<ResponseCode>0</ResponseCode>
	<GetPathInfo>
		<ItemName>F8.jpg</ItemName>
		<IsFile>true</IsFile>
		<CreatedDate>Mon, 09 Mar 2009 02:10:33 GMT</CreatedDate>
		<SizeBytes>566534</SizeBytes>
		<FileType>Image</FileType>
		<Metadata>
			<Metadata FileName="F8.jpg">
				<Data Key="Height">960</Data>
				<Data Key="MD5">vFDnR6xvVvIYJS64vuRL9A==</Data>
				<Data Key="Width">1280</Data>
			</Metadata>
		</Metadata>
		<Tags />
		<IsShared>true</IsShared>
		<ModifiedDate>Mon, 09 Mar 2009 02:11:07 GMT</ModifiedDate>
		<ItemID>16959956610088753346</ItemID>
	</GetPathInfo>
</Response>

Errors

See code samples using our SDKs GetPathInfo.

back to top

ListFolder

The ListFolder method is used to describe the contents of a folder. It lists the files and folders as well as some basic information about the items, such as the file size, metadata, tags and created date. This call supports paging.

Input Parameters

Output Values

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="Response">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="ResponseCode" minOccurs="1"/>
                <xs:element ref="ErrorMessage" minOccurs="0"/>
                <xs:element name="ListFolder">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element ref="TotalFolderCount" minOccurs="1"/>
                            <xs:element ref="TotalFileCount" minOccurs="1"/>
                            <xs:element ref="PageFolderCount" minOccurs="1"/>
                            <xs:element ref="PageFileCount" minOccurs="1"/>
                            <xs:element ref="Folder" minOccurs="0">
                                <xs:complexType>
                                    <xs:sequence>
                                        <xs:element ref="FolderCount" minOccurs="1"/>
                                        <xs:element ref="FileCount" minOccurs="1"/>
                                        <xs:element ref="Name" minOccurs="1"/>
                                        <xs:element ref="Path" minOccurs="1"/>
                                        <xs:element ref="CreatedDate" minOccurs="1"/>
                                        <xs:element ref="MetaData" minOccurs="1">
                                            <xs:complexType>
                                                <xs:sequence>
                                                    <xs:element ref="Data" minOccurs="0"/>
                                                </xs:sequence>
                                            </xs:complexType>
                                        </xs:element>
                                        <xs:element ref="FileTags" minOccurs="1"/>
                                    </xs:sequence>
                                </xs:complexType>
                            </xs:element>

                            <xs:element ref="File" minOccurs="0">
                                <xs:complexType>
                                    <xs:sequence>
                                        <xs:element ref="SizeBytes" minOccurs="1"/>
                                        <xs:element ref="Name" minOccurs="1"/>
                                        <xs:element ref="Path" minOccurs="1"/>
                                        <xs:element ref="CreatedDate" minOccurs="1"/>
                                        <xs:element ref="MetaData" minOccurs="1">
                                            <xs:complexType>
                                                <xs:sequence>
                                                    <xs:element ref="Data" minOccurs="0"/>
                                                </xs:sequence>
                                            </xs:complexType>
                                        </xs:element>
                                        <xs:element ref="FileTags" minOccurs="1"/>
                                    </xs:sequence>
                                </xs:complexType>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element ref="TotalFolderCount">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>
     <xs:element ref="TotalFileCount">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>
     <xs:element ref="PageFolderCount">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>
     <xs:element ref="PageFileCount">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>
     <xs:element ref="FolderCount">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>
     <xs:element ref="FileCount">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element ref="Name" type="xs:string"/>
     <xs:element ref="Path" type="xs:string"/>
     <xs:element ref="CreatedDate" type="xs:string"/>
     <xs:element ref="SizeBytes">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element ref="Data" type="xs:string"/>
     <xs:element ref="FileTags" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/ListFolder.ashx?sessionToken=YOURSESSIONTOKEN
&folderPath=DirTest/F8&pageNumber=1&pageSize=5&sortCode=Name&sortDescending=false

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <ListFolder>

      <TotalFolderCount>3</TotalFolderCount>
      <TotalFileCount>312509</TotalFileCount>
      <PageFolderCount>3</PageFolderCount>
      <PageFileCount>2</PageFileCount>

      <Folder>
         <FolderCount>0</FolderCount>
         <FileCount>1</FileCount>
         <Name>F8AChild</Name>
         <Path>DirTest/F8/F8AChild</Path>
         <CreatedDate>Wed, 02 May 2007 13:36:41 GMT</CreatedDate>
         <Metadata/>
         <FileTags>these|are|my|tags</FileTags>
      </Folder>

      <File>
         <SizeBytes>1000000</SizeBytes>
         <Name>100000-somefile.txt</Name>
         <Path>DirTest/F8/100000-somefile.txt</Path>
         <CreatedDate>Wed, 02 May 2007 15:14:14 GMT</CreatedDate>
         <Metadata>
            <MetaData FileName="100000-somefile.txt">
               <Data Key="MD5">tsDn43abFtxCSTdvuRA2BA==</Data>
            </MetaData>
         </Metadata>
         <FileTags></FileTags>
      </File>

      <File>
         <SizeBytes>566534</SizeBytes>
         <Name>DSC05829.JPG</Name>
         <Path>DirTest/F8/DSC05829.JPG</Path>
         <CreatedDate>Tue, 01 Sep 2009 21:55:31 GMT</CreatedDate>
         <Metadata>
            <MetaData FileName="DSC05829.JPG">
               <Data Key="Width">1280</Data>
               <Data Key="Height">960</Data>
               <Data Key="MD5">vFDnR6xvVvIYJS64vuRL9A==</Data>
            </MetaData>
         </Metadata>
         <FileTags></FileTags>
      </File>

   </ListFolder>
</response>

Errors

See code samples using our SDKs ListFolder.

back to top

MoveFiles

The MoveFiles method is used to move a file from one location to another. The MoveFiles method can be used to move one or more files to a given folder. If the destination folder specified by destFolderPath does not exist it will be created before moving the files.

The maximum size for any path is 512 characters. If a file is moved into a folder and the resulting file path is more that 512 characters long, the file will become unusable. Any attempt to access or rename this file, or list the contents of the parent folder will result in the following error: 70009 - Path is longer than the maximum allowable length of 512. If an array of parameters is passed and there is an error while processing those paths the entire call will be rolled back. If folders were created for some of the paths provided they will not be removed after the error has occurred.

Input Parameters

Output Values

Output Values

A Response Code is always returned. If an error occurred, an Error Message is returned.

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/MoveFiles.ashx?sessionToken=YOURSESSIONTOKEN
&srcFilPath=Folder/subfolder/samplefile.txt&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs MoveFiles.

back to top

MoveFolders

The MoveFolders method is used to move a folder from one location to another. The MoveFolders method can be used to move one or more folders.

The maximum size for any path is 512 characters. When a folder is copied into another folder any resulting file path that is more that 512 characters long will become unusable. Any attempt to access or rename this file or folder, or list the contents of the parent folder will result in the following error: 70009 - Path is longer than the maximum allowable length of 512.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/MoveFolders.ashx?sessionToken=YOURSESSIONTOKEN
&srcFolderPath=Folder/subfolder/FolderToCopy&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs MoveFolders.

back to top

RenameFile

The RenameFile method is used to rename a file from one name to another.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/RenameFile.ashx?sessionToken=YOURSESSIONTOKEN
&filePath=Folder/subfolder/samplefile.txt&newFileName=mynewfile.txt

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Errors

See code samples using our SDKs RenameFile.

back to top

RenameFolder

The RenameFolder method is used to rename a folder from one name to another.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/RenameFolder.ashx?sessionToken=YOURSESSIONTOKEN
&folderPath=Folder/subfolder/myfolder&newFolderName=mynewfolder

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs RenameFolder.

back to top

GetDownloadNodes

The GetDownloadNodes method is used to obtain the current optimum download nodes for one or more files. When passing in more than one path the array returned will be returned in the same order as the paths you have passed in input parameters. Although the download location for each file is subject to change, this should rarely happen. Some of the events that would cause a change are:

• The file has been cached at another node closer to the user.
• The file has been removed from the node due to lack of access.
• The node temporarily cannot serve the file due to hardware failure.
• The node is down for maintenance.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">

      <xs:complexType>
         <xs:sequence>
           <xs:element name="ResponseCode" type="xs:integer" />
           <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />

           <xs:element name="DownloadNode" maxOccurs="unbounded" type="xs:string" />
         </xs:sequence>
      </xs:complexType>

   </xs:element>
</xs:schema>

Sample REST Request

/ws/IMFS/GetDownloadNodes.ashx?sessionToken=YOURSESSIONTOKEN
&filePath=My%20Folder/My%20File%201.txt

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>

   <DownloadNode>node1.nirvanix.com</DownloadNode>
</Response>

Errors

See code samples using our SDKs GetDownloadNodes.

back to top

GetOptimalUrls

The GetOptimalUrls method is used to obtain the current optimum download links for one or more files. These links can be used by anyone to download the associated files within a limited time window. The links can also optionally be restricted to a single IP address. Due to the nature of the SDN and the ability to move files to other locations around the world, the expiration time should be set as low as possible for your particular application. This ensures that if there is a problem with a node you will always be able to access your files. Should the file become unavailable you should request a new download URL to get the file from an alternate location on the SDN.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>

         <xs:sequence>
           <xs:element name="ResponseCode" type="xs:integer" />
           <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />

           <xs:element name="Download" maxOccurs="unbounded " />
              <xs:complexType>
                 <xs:sequence>
                    <xs:element name="FilePath" type="xs:string" />
                    <xs:element name="DownloadHost" type="xs:string" />
                    <xs:element name="DownloadToken" type="xs:string" />
                    <xs:element name="DownloadURL" type="xs:string" />
                 </xs:sequence>
              </xs:complexType>
           </xs:element>

         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Sample REST Request

/ws/IMFS/GetOptimalUrls.ashx?sessionToken=YOURSESSIONTOKEN
&filePath=My%20Folder/My%20File%201.txt&expiration=300

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>

<Response>
   <ResponseCode>0</ResponseCode>
   <Download>
      <FilePath>My Folder/My File 1.txt</FilePath>
      <DownloadHost>node1.nirvanix.com</DownloadHost>
      <DownloadToken>
         Goh7ot5p~BeuoQ45icq~L9TM2Ksh~xT3bfBueAT~Ocp_3AE
      </DownloadToken>
      <DownloadURL>
         http://node1.nirvanix.com/Goh7ot5p~BeuoQ45icq~L9TM2Ksh~xT3bfBueAT~Ocp_3AE/My%20Folder/My%20File%201.txt
      </DownloadURL>
   </Download>
</Response>

Errors

See code samples using our SDK's GetOptimalUrls.

back to top

GetStorageNodeExtended

The GetStorageNodeExtended method is used to obtain the current optimum node to upload files with additional advanced options. The IP address of the consumer of the upload token and whether the token is restricted to this IP address can be optionally specified. The destination folder path must be provided which restricts the returned token to uploading to that specified folder only. An optional flag can be set which allows a file to be overwritten if a file with the same name exists in the destination folder. The token expiration for the first byte and last byte can also be specified. If the file is not uploaded before the expiration period has elapsed, the upload token expires and becomes useless.

Note: A question that often comes up is the size of the download passed to the GetStorageNode and GetStorageNodeExtended when using a web client to upload. In these instances you will not know the size ahead of time and should instead use the best guess for the file size such as the average file size for you.

Note: that reuse of a upload token can lead to corruption or collisions and every upload should use its own token.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="ResponseCode" type="xs:integer" />
            <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
            <xs:element name="GetStorageNode">
               <xs:complexType>
                  <xs:sequence>
                    <xs:element name="UploadHost" maxOccurs="1" />
                    <xs:element name="UploadToken" maxOccurs="1" />
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Sample REST Request

/ws/IMFS/GetStorageNodeExtended.ashx?sessionToken=YOURSESSIONTOKEN&
sizeBytes=450000&consumerIP=127.0.0.1&ipRestricted=true&destFolderPath=/&
fileOverwrite=true&firstByteExpiration=6000&lastByteExpiration=259200

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>

<Response>
   <ResponseCode>0</ResponseCode>
   <GetStorageNode>
      <UploadHost>node1.nirvanix.com</UploadHost>
      <UploadToken>kMHib15S~c_5IY1CphI~7cFRwvOB~E5evmH0CaL~WccWTQ_Vbu0yJGctig</UploadToken>
   </GetStorageNode>
</Response>

Errors

See code samples using our SDKs GetStorageNodeExtended.

back to top

GetStorageNode

The GetStorageNode method is used to determine which storage node a file should be uploaded to. It returns the host to upload to and an Upload Token that will be used to authenticate. The token expiration for the first byte is 10 minutes, the last byte is 3 days. Also see GetStorageNodeExtended

Note: A question that often comes up is the size of the download passed to the GetStorageNode and GetStorageNodeExtended when using a web client to upload. In these instances you will not know the size ahead of time and should instead use the best guess for the file size such as the average file size for you.

Note: that reuse of a upload token can lead to corruption or collisions and every upload should use its own token.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="ResponseCode" type="xs:integer" />
            <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
            <xs:element name="GetStorageNode">
               <xs:complexType>
                  <xs:sequence>
                    <xs:element name="UploadHost" maxOccurs="unbounded" />
                    <xs:element name="UploadToken" maxOccurs="unbounded" />
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Sample REST Request

/ws/IMFS/GetStorageNode.ashx?sessionToken=YOURSESSIONTOKEN&sizeBytes=1024

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <GetStorageNode>
      <UploadHost>node1.nirvanix.com</UploadHost>
      <UploadToken>myuploadtoken</UploadToken>
   </GetStorageNode>
</Response>

Errors

See code samples using our SDKs GetStorageNode.

back to top

SearchFileSystem

The SearchFileSystem method is used to search for items in your file system that match the specified search criteria.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="ResponseCode" minOccurs="1" type="xs:integer" />
            <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
            <xs:element name="Response">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element name="SearchCount" minOccurs="1" type="xs:integer" />
                     <xs:element name="Item" minOccurs="0" maxOccurs="10000" >
                        <xs:complexType>
                           <xs:sequence>
                              <xs:element name="ItemPath" minOccurs="1" type="xs:string" />
                              <xs:element name="ItemName" minOccurs="1" type="xs:string" />
                              <xs:element name="CreatedDate" minOccurs="1" type="xs:string" />
                              <xs:element name="SizeBytes" minOccurs="1" type="xs:integer" />
                              <xs:element name="FileType" minOccurs="1" type="xs:string" />
                              <xs:element name="IsFile" minOccurs="1" type="xs:boolean" />
                           </xs:sequence>
                        </xs:complexType>
                     </xs:element>
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Sample REST Request

/ws/IMFS/SearchFileSystem.ashx?sessionToken=YOURSESSIONTOKEN
&username=myuser&fileType=Video&minFileSize=0&maxFileSize=100000000
&minCreatedDate=7/1/2007&maxCreatedDate=9/1/2007&maxResults=1000

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <SearchResults>
      <SearchCount>1</SearchCount>
      <Item>
         <ItemPath>joebriggs.avi</ItemPath>
         <ItemName>joebriggs.avi</ItemName>
         <CreatedDate>Wed, 12 Sep 2007 11:06:46 GMT</CreatedDate>
         <SizeBytes>7283012</SizeBytes>
         <FileType>Video</FileType>
         <IsFile>true</IsFile>
      </Item>
   </SearchResults>
</Response>

Errors

See code samples using our SDKs SearchFileSystem.

back to top

Sideload

The Sideload command allows a user to load remote content into their Nirvanix file system. When submitting the targetURL for sideloading it will be placed in a queue and the response will signal that the item has been successfully placed in the queue. This does not mean that the sideload has completed but that it has been successfully scheduled. To get the results of the actual sideload event you will need to provide a callback URL. When the sideload URL has been processed the results will be sent to the callback URL specified with a success result or error message and code.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/IMFS/Sideload.ashx?sessionToken=YOURSESSIONTOKEN
&targetURL=http://mywebsite.com/default.html&destFilePath=mywebpages/default.html

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs Sideload.

back to top

Metadata Namespace

Nirvanix Web Services implements the industry standard REST and SOAP protocols allowing end users to upload, copy, move, and delete files and folders. Furthermore, end users can retrieve a listing of their files and also associate user-defined tags and metadata.

Metadata refers to a specific type of information about a specific type of file. Nirvanix Web Services supports any type of metadata.

The Nirvanix Web Services API provides both a REST and SOAP interface for manipulating metadata. The following standard metadata types are supported; however you can create any type of metadata you desire:

• Width
• Height
• Duration
• BitRate
• FrameRate
• Title
• Artist
• Album
• Genre
• Track
• IsVariableBitRate

DeleteAllMetadata

The DeleteAllMetadata method is used to remove all metadata from a file or folder. Please note that the MD5 metadata type will NOT be removed with this call.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/DeleteAllMetadata.ashx?sessionToken=YOURSESSIONTOKEN
&path=Folders/subfolder/myfile.txt

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs DeleteAllMetadata.

back to top

DeleteMetadata

The DeleteMetadata method is used to remove specified metadata from a file or folder.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/DeleteMetadata.ashx?sessionToken=YOURSESSIONTOKEN
&path=Folders/subfolder/myfile.txt&metadata=Width

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs DeleteMetadata.

back to top

GetMetadata

The GetMetadata method is used to retrieve all metadata from a file or folder.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="ResponseCode" minOccurs="1"/>
            <xs:element ref="ErrorMessage" minOccurs="0"/>

            <xs:element name="Metadata" minOccurs="0" >
               <xs:complexType>
                  <xs:sequence>
                     <xs:element ref="Type" minOccurs="1" type="xs:string"/>
                     <xs:element ref="Value" minOccurs="1" type="xs:string"/>
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <xs:element name="ResponseCode">
      <xs:simpleType>
         <xs:restriction base="xs:integer" />
      </xs:simpleType>
   </xs:element>

   <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/GetMetadata.ashx?sessionToken=YOURSESSIONTOKEN
&sourcePath=Folders/subfolder/myfile.txt

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>

<Response>
   <ResponseCode>0</ResponseCode>
   <Metadata>
     <Type>BitRate</Type>
     <Value>4444</Value>
  </Metadata>
</Response>

Errors

See code samples using our SDKs GetMetadata.

back to top

SetMetadata

The SetMetadata method is used to set specified metadata for a file or folder.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/SetMetadata.ashx?sessionToken=YOURSESSIONTOKEN
&path=Folders/subfolder/myfile.txt&metadata=Title:MySong

Sample REST XML Response

<Response>
  <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs SetMetadata.

back to top

DeleteAllTags

The DeleteAllTags method is used to remove all tags from a file or folder.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/DeleteAllTags.ashx?sessionToken=YOURSESSIONTOKEN
&path=Folders/subfolder/myfile.txt

Sample REST XML Response

<Response>
  <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs DeleteAllTags.

back to top

DeleteTags

The DeleteTags method is used to remove specified tags from a file or folder.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/DeleteTags.ashx?sessionToken=YOURSESSIONTOKEN
&path=Folders/subfolder/myfile.txt&tag=foo&tag=bar

Sample REST XML Response

<Response>
  <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs DeleteTags.

back to top

GetTags

The GetTags method is used to retrieve all tags from a file or folder.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="ResponseCode" minOccurs="1"/>
            <xs:element ref="ErrorMessage" minOccurs="0"/>
            <xs:element name="Tag" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <xs:element name="ResponseCode">
      <xs:simpleType>
         <xs:restriction base="xs:integer" />
      </xs:simpleType>
   </xs:element>

   <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/GetTags.ashx?sessionToken=YOURSESSIONTOKEN
&path=Folders/subfolder/myfile.txt

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
   <Tag>foo</Tag>
   <Tag>bar</Tag>
</Response>

Errors

See code samples using our SDKs GetTags.

back to top

SetTags

The SetTags method is used to set specified tags for a file or folder.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Metadata/SetTags.ashx?sessionToken=YOURSESSIONTOKEN
&path=Folders/subfolder/myfile.txt&tag=foo&tag=bar

Sample REST XML Response

<Response>
  <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs SetTags.

back to top

SearchMetadata

The SearchMetadata method is used to search for items in your file system that match the specified metadata search criteria.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="ResponseCode" minOccurs="1" type="xs:integer" />
            <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
            <xs:element name="Response">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element name="SearchCount" minOccurs="1" type="xs:integer" />
                     <xs:element name="Item" minOccurs="0" maxOccurs="10000" >
                        <xs:complexType>
                           <xs:sequence>
                              <xs:element name="ItemPath" minOccurs="1" type="xs:string" />
                              <xs:element name="ItemName" minOccurs="1" type="xs:string" />
                              <xs:element name="CreatedDate" minOccurs="1" type="xs:string" />
                              <xs:element name="SizeBytes" minOccurs="1" type="xs:integer" />
                              <xs:element name="FileType" minOccurs="1" type="xs:string" />
                              <xs:element name="IsFile" minOccurs="1" type="xs:boolean" />
                           </xs:sequence>
                        </xs:complexType>
                     </xs:element>
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Sample REST Request

/ws/Metadata/SearchMetadata.ashx?sessionToken=YOURSESSIONTOKEN&
username=myuser&searchKey=Duration&searchTerm=3*&maxResults=1000

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>

<Response>
   <ResponseCode>0</ResponseCode>
   <SearchResults>
      <SearchCount>1</SearchCount>
      <Item>
         <ItemPath>joebriggs.avi</ItemPath>
         <ItemName>joebriggs.avi</ItemName>
         <CreatedDate>Wed, 12 Sep 2007 11:06:46 GMT</CreatedDate>
         <SizeBytes>7283012</SizeBytes>
         <FileType>Video</FileType>
         <IsFile>true</IsFile>
      </Item>
   </SearchResults>
</Response>

Errors

See code samples using our SDKs SearchMetadata.

back to top

SearchTags

The SearchTags method is used to search for items in your file system that match the specified tag search criteria.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="ResponseCode" minOccurs="1" type="xs:integer" />
            <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
            <xs:element name="Response">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element name="SearchCount" minOccurs="1" type="xs:integer" />
                     <xs:element name="Item" minOccurs="0" maxOccurs="10000" >
                        <xs:complexType>
                           <xs:sequence>
                              <xs:element name="ItemPath" minOccurs="1" type="xs:string" />
                              <xs:element name="ItemName" minOccurs="1" type="xs:string" />
                              <xs:element name="CreatedDate" minOccurs="1" type="xs:string" />
                              <xs:element name="SizeBytes" minOccurs="1" type="xs:integer" />
                              <xs:element name="FileType" minOccurs="1" type="xs:string" />
                              <xs:element name="IsFile" minOccurs="1" type="xs:boolean" />
                           </xs:sequence>
                        </xs:complexType>
                     </xs:element>
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Sample REST Request

/ws/Metadata/SearchTags.ashx?sessionToken=YOURSESSIONTOKEN&
username=myuser&searchTerm=mytag*&maxResults=1000

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>

<Response>
   <ResponseCode>0</ResponseCode>
   <SearchResults>
      <SearchCount>1</SearchCount>
      <Item>
         <ItemPath>joebriggs.avi</ItemPath>
         <ItemName>joebriggs.avi</ItemName>
         <CreatedDate>Wed, 12 Sep 2007 11:06:46 GMT</CreatedDate>
         <SizeBytes>7283012</SizeBytes>
         <FileType>Video</FileType>
         <IsFile>true</IsFile>
      </Item>
   </SearchResults>
</Response>

Errors

See code samples using our SDKs SearchTags.

back to top

Sharing Namespace

For Nirvanix Web Services 1.0 the sharing component only consists of hosting functionality. Host links are paths where everyone has read access. This could be used to host a website, share images, or other media, or to email links to files in a Nirvanix IFS account. A hosted link may be embedded into a webpage and presented as a standard ordinary web-hosted file. The return value would be the URL for the file or folder. The owner of the hosted item will always be the one charged for the download.

ListHostedItems

The ListHostedItems method is used to list all of the files and folders that the user has hosted.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="ResponseCode" minOccurs="1"/>
            <xs:element ref="ErrorMessage" minOccurs="0"/>
            <xs:element name="HostedItem">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element name="IsFile" type="xs:boolean" minOccurs="1"/>
                     <xs:element name="SharePath" type="xs:string" minOccurs="1"/>
                  </xs:sequence>
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <xs:element name="ResponseCode">
      <xs:simpleType>
         <xs:restriction base="xs:integer" />
      </xs:simpleType>
   </xs:element>

   <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Sharing/ListHostedItems.ashx?sessionToken=YOURSESSIONTOKEN
&pageNumber=1&pageSize=10

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>

<Response>
   <ResponseCode>0</ResponseCode>
   <HostedItem>
      <IsFile>false</IsFile>
      <SharePath>MyFolder/MySubfolder</SharePath>
   </HostedItem>
   <HostedItem>
      <IsFile>true</IsFile>
      <SharePath>MyFolder/MySharedFile.txt</SharePath>
   </HostedItem>
</Response>

Errors

See code samples using our SDKs ListHostedItems.

back to top

CreateHostedItem

The CreateHostedItem method is used to allow any user to have read access to a file or folder. If a folder is hosted, then everyone has read access to all its contents which includes any folders or files under it.

Please note that it may take up to 5 minutes for any file changes (e.g. move, rename and remove) to propagate after a hosted item is created.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="ResponseCode" minOccurs="1"/>
            <xs:element ref="ErrorMessage" minOccurs="0"/>
            <xs:element name="DownloadLink" type="xs:string" minOccurs="0"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>

   <xs:element name="ResponseCode">
      <xs:simpleType>
         <xs:restriction base="xs:integer" />
      </xs:simpleType>
   </xs:element>

   <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Sharing/CreateHostedItem.ashx?sessionToken=YOURSESSIONTOKEN
&sharePath=Folder/subfolder/samplefile.txt

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
   <DownloadLink>http://mylinktodownloadthisfile.com</DownloadLink>
</Response>

Errors

See code samples using our SDKs CreateHostedItem.

back to top

RemoveHostedItem

The RemoveHostedItem method is used to remove the read access from everyone but the owner from a file or folder.

Please note that it may take up to 5 minutes for this method to take effect.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Sharing/RemoveHostedItem.ashx?sessionToken=YOURSESSIONTOKEN
&sharePath=Folder/subfolder/samplefile.txt

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs RemoveHostedItem.

back to top

Transfer Namespace

This namespace of the Nirvanix Web Services provides a set of API methods that allow a user to upload files to our Internet File System (IFS). An HTTP upload interface is also provided which is the preferred method of transport due to the overhead of SOAP.

AppendFile (SOAP ONLY)

The AppendFile method is used to upload a file in parts. If the path does not exist it will be created.

For example, if filename is "Vacations\2007\Hawaii\beachDay1.jpg" then when the file is done uploading the file would be added to Vacations\2007\Hawaii\beachDay1.jpg".  The system creates all the folders that do not exist in this scenario.

With the HTTP Upload you can pass multiple files at once but for the AppendFile (SOAP) you can pass multiple files but only over multiple calls. A good example of using AppendFile to upload multiple files at once would be under a multithreaded application where each thread is uploading its own file. As long as each path being passed is different this will work correctly since we identify which file you are uploading by the path you pass.

Note: If you receive a transmission error or partial transmission you must call GetStorageNode to retrieve a new token and you must resend your file from byte 0.

Input Parameters

Output Values

None

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
StorageNode node = nirvFS.GetStorageNode(sessionToken, 1024);
Nirvanix.Transfer nirvTransfer = new Nirvanix.Transfer();
UriBuilder uriBuilder = new UriBuilder(nirvTransfer.Url);
uriBuilder.Host = node.Host;
nirvTransfer.Url = uriBuilder.ToString();
nirvTransfer.AppendFile(node.AccessToken, "Folder/mynewfile.jpg", fileData, false);
nirvTransfer.AppendFile(node.AccessToken, "Folder/mynewfile.jpg", fileData, true);

Sample SOAP Response

Go to WSDL for AppendFile.

UploadFile (SOAP ONLY)

The UploadFile method is used to upload a file in its entirety. If the path does not exist it will be created. The maximum file size for uploading a file using this interface is 2 GB. If your file is larger than 2 GB, you must use the AppendFile method.

For example, if filename is "Vacations\2007\Hawaii\beachDay1.jpg" then when the file is done uploading the file would be added to "Vacations\2007\Hawaii\beachDay1.jpg". The system creates all the folders that do not exist in this scenario.

Input Parameters

Output Values

None

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
StorageNode node = nirvFS.GetStorageNode(sessionToken, 1024);
Nirvanix.Transfer nirvTransfer = new Nirvanix.Transfer();
UriBuilder uriBuilder = new UriBuilder(nirvTransfer.Url);
uriBuilder.Host = node.Host;
nirvTransfer.Url = uriBuilder.ToString();

nirvTransfer.UploadFile(node.AccessToken, "Folder/mynewfile.jpg", fileData);

Sample SOAP Response

Go to WSDL for UploadFile.

HTTP Upload

Please refer to the Uploading Files section for extensive information on HTTP Upload.

Video Namespace

The Video Namespace allows a user to convert a video file from one format to another with the ability to specify optional parameters such as number of frames, frame rate, width, height, and aspect ratio.

PresetTranscode

The PresetTranscode method is used to convert a video file from one format to another.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Video/PresetTranscode.ashx?sessionToken=YOURSESSIONTOKEN&
srcFilePath=myvideo.mpg&destFilePath=myvideo.flv&preset=H263+FLV+Medium&scaleWidth=640&scaleHeight=480

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs PresetTranscode.

back to top

Transcode

The Transcode method is used to convert a video file from one format to another.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Video/Transcode.ashx?sessionToken=YOURSESSIONTOKEN
&srcFilePath=myvideo.mpg&destFilePath=myvideo.flv&numberOfFrames=10000&frameRate=24&width=640&height=480&aspectRatio=
1.33&audioFreq=44100

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs Transcode.

back to top

ExtractFrames

The ExtractFrames method will extract frames from a video file and store them as images.

Input Parameters

Output Values

REST XSD

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="Response">
         <xs:complexType>
              <xs:sequence>
                   <xs:element ref="ResponseCode" minOccurs="1"/>
                   <xs:element ref="ErrorMessage" minOccurs="0"/>
              </xs:sequence>
         </xs:complexType>
     </xs:element>

     <xs:element name="ResponseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />
         </xs:simpleType>
     </xs:element>

     <xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>

Sample REST Request

/ws/Video/ExtractFrames.ashx?sessionToken=YOURSESSIONTOKEN
&srcFilePath=myvideo.mpg&destFolderPath=myFrameFolder&numberOfFrames=10000&frameName=MyFrame

Sample REST XML Response

<Response>
<ResponseCode>0</ResponseCode>
</Response>

Errors

See code samples using our SDKs ExtractFrames.

back to top

Exception Framework

When an exception occurs, they often contain information useful to the user. If a path was misspelled or a session token expired, the user should be told what went wrong. The exception framework helps convert all Nirvanix exceptions into a consistent xml response, while hiding any proprietary programming information.

Every web service method interacts with the Exception Framework to provide consistent, meaningful, non-technical responses to errors. If an exception is thrown, the outermost layer of the web service will catch the exception, and return two meaningful pieces: a Response Code and an Error Message.

Input Parameters

Output Values

A Response Code and Error Message is returned.

SOAP and REST XSD

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element ref="ResponseCode" />

     <xs:element ref="ErrorMessage" />
</xs:schema>

Sample REST Response

<?xml version="1.0" encoding="UTF-8"?>

<response>
     <ResponseCode>80101</ responseCode>
     <ErrorMessage>Invalid Session Token</errorMessage>
</response>

Sample SOAP Response

SOAP Header
Beginning of SOAP Body

<response ns="NirvanixException">
     <responseCode>82005</ responseCode>
     <errorMessage>Invalid Session Token</errorMessage>
</response>

End of SOAP Body

.Net SOAP Use for the Client

If the customer is developing their code in .Net, a SOAP Exception can be caught, and the error response retrieved from the Details property.

C# Example

accounting.CreateChildAccount() uses a Web Reference to make the SOAP call.

int responseCode = -1;
XmlNode xmlDetailNode;
int errorCode = 0;
int errorMessage = string.Empty;
try
{
    responseCode = accounting.CreateChildAccount();
}
catch (SoapException ex)
{
    xmlDetailNode = ex.Detail;
    errorCode = int.Parse(
        xmlDetailNode.SelectSingleNode("Response/ResponseCode").InnerText );

    errorMessage = xmlDetailNode.SelectSingleNode("Response/ErrorMessage").InnerText;
}

If the Create Child Account SOAP call returns a Soap Exception, It will be caught, and the error response xml will be loaded into the xmlDetailNode. The values can then be read and loaded into the ResponseCode and ErrorMessage variables.

Errors

Appendices

Date Format

Passing dates to the Nirvanix API require a specific format based on RFC and W3C Standards. Below is an example of a full date and time format that can be used with our system followed by the standards information associated with the acceptable date formats.

RFC 822 Date and Time Specification (Partial See RFC 822.)

date-time       =       [ day-of-week "," ] date FWS time [CFWS]

day-of-week     =       ([FWS] day-name) / obs-day-of-week

day-name        =       "Mon" / "Tue" / "Wed" / "Thu" /
                        "Fri" / "Sat" / "Sun"

date            =       day month year

year            =       4*DIGIT / obs-year

month           =       (FWS month-name FWS) / obs-month

month-name      =       "Jan" / "Feb" / "Mar" / "Apr" /
                        "May" / "Jun" / "Jul" / "Aug" /
                        "Sep" / "Oct" / "Nov" / "Dec"

day             =       ([FWS] 1*2DIGIT) / obs-day

time            =       time-of-day FWS zone

time-of-day     =       hour ":" minute [ ":" second ]

hour            =       2DIGIT / obs-hour

minute          =       2DIGIT / obs-minute

second          =       2DIGIT / obs-second

zone            =       (( "+" / "-" ) 4DIGIT) / obs-zone
  

W3C Date and Time Format (See W3C Date and Time Format)

1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.

For HTTP applications, the date and time format is specified in RFC 2616 which is the format defined in RFC 1123 (which is an update to RFC 822, changing the year format from YY to YYYY). This is currently supported under our Web services on both input and output. A second format supported by our Web services is the WC3 Datetime Format which is a profile of a broader standard defined in ISO 8601.

Country Codes for Web Services

When creating and updating accounts, the Nirvanix Web Services uses the CountryID parameter to set the country. Every country has a unique country id.

back to top

SOAP WSDL URLs

The namespaces below are groupings of methods for our SOAP Web Services and are not to be confused with a file system namespace, in which files can be grouped into folders, and folders can live inside other folders with other files (directory tree). Each of the namespaces below has a separate WSDL document describing those Web Services included in each namespace.

Authentication Namespace

http://services.nirvanix.com/ws/Authentication.asmx?WSDL

Account Management Namespace

http://services.nirvanix.com/ws/Accounting.asmx?WSDL

IMFS Namespace

http://services.nirvanix.com/ws/IMFS.asmx?WSDL

Metadata Namespace

http://services.nirvanix.com/ws/Metadata.asmx?WSDL

Sharing Namespace

http://services.nirvanix.com/ws/Sharing.asmx?WSDL

Image Namespace

http://services.nirvanix.com/ws/Image.asmx?WSDL

Transfer Namespace

http://node1.nirvanix.com/ws/Transfer.asmx?WSDL

Audio Namespace

http://services.nirvanix.com/ws/Audio.asmx?WSDL

Video Namespace

http://services.nirvanix.com/ws/Video.asmx?WSDL

back to top

Image Conversion Formats

The Image Resize method allows creating new files from an existing image file. Below are the formats that are allowed in this method.

back to top

Audio Transcode Formats / Codecs

The list below is broken into format and codec since the file format may not always dictate the codec being used for that file.

Audio Formats (Does not include codecs)

Audio Codecs (Independent of file format)

back to top

Video PresetTranscode Formats / Codecs

The list below is broken into format and codec since the file format may not always dictate the codec being used for that file. A separate list of audio codecs handled is also given for our video processor.

Video Formats (Does not include codecs)

Video Codecs (Independent of file format)

Video PresetTranscode Audio Codecs (Independent of file format)

back to top