• 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 Media File System?

When to use an IMFS?

Web Services Overview

Calling Nirvanix Web Services

SOAP

REST

HTTP GET

The Nirvanix Media Filesystem Overview

Understanding Nirvanix Namespaces

Why are Namespaces important?

Authentication Namespace

Account Management Namespace

IMFS Namespace

Metadata Namespace

Sharing Namespace

Image Namespace

Transfer Namespace

Audio Namespace

Video Namespace

Setting up Nirvanix MFS

Master Accounts

Creating Master Accounts

Child Accounts

Creating Child Accounts

Deleting Child Accounts

Managing Child Account Information

Authentication

Accessing Nirvanix MFS

Creating Directories or Folders

Manipulating Files and Folders

Uploading Files

SOAP

HTTP Upload

Downloading Files

Request URL

Nirvanix Extensibility

Metadata

Tags

Sharing

Authentication Namespace

Customer API

Login

LoginProxy

Logout

ChangePassword

SetChildAccountPassword

Internet Media File System (IMFS) Namespace

Customer API

Common Errors

CopyFiles

CopyFolders

CreateFolders

DeleteFiles

DeleteFolders

GetPathInfo

ListFolder

MoveFiles

MoveFolders

RenameFile

RenameFolder

GetDownloadNodes

GetOptimalUrls

GetStorageNodeExtended

GetStorageNode

SearchFileSystem

Sideload

Metadata Namespace

Customer API

DeleteAllMetadata

DeleteMetadata

GetMetadata

SetMetadata

DeleteAllTags

DeleteTags

GetTags

SetTags

SearchMetadata

SearchTags

Sharing Namespace

Customer API

ListHostedItems

CreateHostedItem

RemoveHostedItem

Image Namespace

Resize

RotateFlip

Download Component

Customer API

HTTP Get

Transfer Namespace

Customer API

AppendFile

UploadFile

HTTP Upload

HTTP Update

Accounting Namespace

Customer API

CreateChildAccount

DeleteChildAccount

GetAccountUsage

GetAccountLimits

SetAccountLimits

GetAccountInfo

SetAccountInfo

GetAccountNotes

SetAccountNotes

GetStorageUsage

ListChildAccounts

Audio Namespace

Customer API

Transcode

Video Namespace

Customer API

PresetTranscode

Transcode

ExtractFrames

Virtual URL Hosting

Glossary

Managing Virtual URLs

Propagation Times

Mapped Zones

Generating Transfer Paths for Mapped Virtual URLs

Using Web Services with Virtual URLs

Miscellaneous

Exception Framework

Customer API

Appendices

Date Formats

Country Codes for Web Services

HTTP Update Examples

API Developer's Guide v1.0

Release 2.3.3

6/17/2009

Getting Started: An introduction to key concepts

What is an Internet Media File System?

An Internet Media File System (IMFS) 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 IMFS is distributed clustered file system, accessed over the Internet, and optimized for dealing with media files (audio, video, etc). The goal of an IMFS is to provide massive scalability to deal with the challenges of media storage growth, with guaranteed access and availability regardless of time and location. Finally, an IMFS gives applications the ability to access data securely, without the large fixed costs associated with acquiring and maintaining physical storage assets.

An IMFS is:

• A file system for the Internet
• Implemented as a cluster of nodes
• Accessed via Web Services
• Consumed on-demand, as a service
• Optimized for managing media (large files, streaming video/audio, processing images, etc)
• Completely secure and protected

When to use an IMFS?

Internet Media File Systems are great solutions for developers working on applications dealing with user-generated content services, fixed content storage, community-based media sharing applications, video/music/photo management, and archival solutions. Instead of building a storage file system from scratch or buying an expensive storage solution, developers can avoid the upfront cost and ongoing maintenance windows by simply connecting to an online storage service. The richer the feature set of this service, the lower the effort on application development and the faster the time to get to market.

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 multi-million user account management and security. These core competencies can be leveraged when storage services are provided by an IMFS. Another benefit of using an IMFS is in cases where there is resource contention associated with IT budgeting and staffing. An IMFS model provides a pay-as-you-go pricing model that scales with usage.

At the same time, an IMFS 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 Media File Service (Nirvanix MFS) was built and optimized for managing user-generated content, ease of integration, ease of scalability, and ease of control.

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

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.

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.

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=8da051b0-a60f-4c22-a8e0-d9380edafa6f&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/admin/web/index.html
Relative: web/index.html

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.

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. For example, this API call

/ws/IMFS/ListFolder.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f&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>

HTTP GET

See section 9.3of RFC 2616 for information about GET and partial GET.

The Nirvanix Media File System Overview

The Nirvanix MFS is a proprietary file system that scales to exabytes with a single global namespace. It has a rich set of web service methods in its interface that allows for advanced storage application development in record time, providing developers with a great time-to-market advantage versus any other service or building infrastructure from scratch.

Understanding Nirvanix Namespaces

Why are Namespaces important?

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. 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. However, in this version of the API method calls are unique and namespaces mainly provide a means of grouping logically related methods into corresponding namespaces, thereby making the system more modular.

The namespaces below are groupings of methods for our 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

Setting up Nirvanix MFS

There are two types of accounts in our IMFS system, 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 MFS 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 for multiple services. When you create a master account, the first Application is created for you.

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 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 DeleteChildAccounts command lets you remove child accounts. 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 accountConfigXML can be set allowing for per account configuration to be set. 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.

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 MFS. 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. Despite this 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 MFS

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:

\ / : ? | * " < >

Note: slash "/" is reserved as the path delimiter. It cannot be part of a file name or folder name.

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, 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 after 72 hours 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.

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.

SOAP

AppendFile lets you append pieces of a file until the entire file has been sent. Each piece of the file that is sent is stored in a temporary file under the current session you are using. You can continue uploading the same file until the session is invalidated or three days has passed. Any temporary files are removed at that point and you will have to begin uploading the file from the start.

A small example of how to read a file in .Net on the local file system and upload to Nirvanix is shown below.

using (FileStream fs = new FileStream(localPath, FileMode.Open, FileAccess.Read))
{
    using (BinaryReader br = new BinaryReader(fs))
    {
        byte[] fileData;
        do
        {
            // Read a chunk of data from the file.
            fileData = br.ReadBytes(fileChunkSize);

            // Upload some data to the file
            transfer.AppendFile(uploadNode.AccessToken, relativePath, fileData, false);

        } while (fileData.Length == fileChunkSize);

        // This is the end of file, so set the endofFile flag to 'true'
        transfer.AppendFile(uploadNode.AccessToken, relativePath, null, true);
    }
}

HTTP Upload

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 preceed 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.

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.

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 IMFS.

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

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

        Upload Token: <input type="text" name="uploadToken" /><br />
        Upload Folder: <input type="text" name="destFolderPath" /><br />

        File 1: <input type="file" name="uploadFile1"/><br />
        File 2: <input type="file" name="uploadFile2"/><br />

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

Custom Http Uploading

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
\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-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.

Partial File Update

Existing files can be updated by uploading only the changed portions of a file to overwrite using the partial file update call (/Update.ashx). This call will allow you to pass any portion of a file that already exists in your account. To verify the result of the update, we require the MD5 hash of the complete resulting file. The MD5 should be based on the entire updated file, not the MD5 of the content actually transferred. In this case, the Content-Range must adhere to the following guidelines or an error will be returned:

• Multiple ranges may be sent in the same request. However, all ranges in the request must be applied to the same file.
• If multiple ranges are sent, they must not overlap one another.
• If the updated file length is greater than the original length, the added content must be included in one of the ranges.
• Because of the MD5 hash validation, all changed ranges must be sent in a single request.
• If Content-Range is not provided, it is assumed the entire updated file will be uploaded in a single request.

For more details of how Content-Range is used to perform partial file update, please refer to these HTTP Update Examples.

Downloading Files

Request URL

To download a file from the Nirvanix MFS, 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>
 

Optionally, you can also specify the downloads content disposition with the query parameter "disposition". Valid values for this parameter are "inline" and "attachment".

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

To obtain the transfer node, please see the GetDownloadNodes method in the IMFS name space. As an alternative, and to make this a one-step process, you can also make the same download request to services.nirvamix.com and be redirected to the correct transfer node.

Request Headers

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

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

Response Headers

Nirvanix MFS 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

Nirvanix Extensibility

Metadata

Each file can have additional information stored about that file that we store 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.

<Metadata FileName=\"Goodbye Girl.mp3\">
   <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, DeleteTag or DeleteAllTags.

Sharing

Sharing will set one or more folders to be available for viewing by non-authenticated users. This allows functionality such as websites images, 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 an HTTP 306 Response, as defined in RFC 2616 section 10.3.2 301.

Call:
String downloadLink = CreateHostedItem(sessionToken, "FolderShared/");

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 RemoveHostedItems to remove any items you no longer wish to share.

Authentication Namespace

Customer API

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

Sample REST Request

/ws/Authentication/Login.ashx?appKey=8da051b0-a60f-4c22-a8e0-d9380edafa6f&userName=testuser&password=Abc123

Sample REST XML Response

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

   <SessionToken>54592180-7060-4D4B-BC74-2566F4B2F943</SessionToken>
</Response>

Sample SOAP Request

Authentication auth = new Authentication();
string sessionToken = auth.Login(appKey, userName, password);

Sample SOAP Response

Go to WSDL for Login.

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

Sample REST Request

/ws/Authentication/LoginProxy.ashx?appKey=8da051b0-a60f-4c22-a8e0-d9380edafa6f&userName=
testuser&password=Abc123&consumerIP=123.123.123.123

Sample REST XML Response

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

<Response>
   <ResponseCode>0</ResponseCode>
   <SessionToken>54592180-7060-4D4B-BC74-2566F4B2F943</SessionToken>
</Response>

Sample SOAP Request

Authentication auth = new Authentication();
string sessionToken = auth.LoginProxy(appKey, userName, password, consumerIP);

Sample SOAP Response

Go to WSDL for LoginProxy.

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

Sample REST Request

/ws/Authentication/Logout.ashx?sessionToken=54592180-7060-4D4B-BC74-2566F4B2F943

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Authentication nirvAuth = new Authentication();
nirvAuth.Logout(sessionToken);

Sample SOAP Response

Go to WSDL for Logout.

ChangePassword

The ChangePassword is used to change an accounts own password.

Input Parameters

Output Values

Sample REST Request

/ws/Authentication/ChangePassword.ashx?appKey=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&userName=testuser&oldPassword=Abc123&newPassword=Def456

Sample REST XML Response

<Response>

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

Sample SOAP Request

Authentication nirvAuth = new Authentication();
nirvAuth.ChangePassword(appKey, userName, oldPassword, newPassword);

Sample SOAP Response

Go to WSDL for ChangePassword.

SetChildAccountPassword

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

Input Parameters

Output Values

Sample REST Request

/ws/Authentication/SetChildAccountPassword.ashx?appKey=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&userName=MasterUser&password=Abc123&childAccountUsername=testuser&childAccountPassword=Def456

Sample REST XML Response

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

Sample SOAP Request

Authentication nirvAuth = new Authentication();
nirvAuth.SetChildAccountPassword(appKey, userName, password, childAccountUsername, childAccountPassword);

Sample SOAP Response

Go to WSDL for SetChildAccountPassword.

Internet Media File System (IMFS) Namespace

Customer API

All file system operations require the caller to be authenticated. Therefore, all IMFS 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 "8da051b0-a60f-4c22-a8e0-d9380edafa6f" 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 IMFS 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 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.

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 parnt folder will result in the following error: 70009 - Path is longer than the maximum allowable length of 512.

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/CopyFiles.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFilePath=Folder/subfolder/samplefile.txt&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.CopyFiles(sessionToken, new string[]{"Folder/subfolder/samplefile.txt"}, 
"Folder/subfolder/DestFolder";

Sample SOAP Response

Go to WSDL for http://services.nirvanix.com/ws/IMFS.asmx?op=CopyFiles

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.

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

Sample REST Request

/ws/IMFS/CopyFolders.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&
srcFolderPath=Folder/subfolder/FolderToCopy&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.CopyFolders(sessionToken, new string[]{"Folder/subfolder/FolderToCopy"}, 
"Folder/subfolder/DestFolder");

Sample SOAP Response

Go to WSDL for CopyFolders

CreateFolders

The CreateFolder method is used to create a new folder at the specified location.

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/CreateFolders.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&folderPath=Folders/subfolder/NewFolder/1| Folders/subfolder/NewFolder2

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.CreateFolder(sessionToken, new string[]{"Folders/subfolder/NewFolder"});

Sample SOAP Response

Go to WSDL for CreateFolders

DeleteFiles

The DeleteFiles method is used to remove one or more files.

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/DeleteFiles.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&filePath=Folders/subfolder/myfile.txt

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.DeleteFiles(sessionToken, new string[] {"Folders/subfolder/myfile.txt"});

Sample SOAP Response

Go to WSDL for DeleteFiles.

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

Sample REST Request

/ws/IMFS/DeleteFolders.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&folderPath=Folders/subfolder

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

nirvFS.DeleteFolders(sessionToken, new string[] {"FolderNirvanix.IMFS nirvFS = 
new Nirvanix.IMFS();s/subfolder"});

Sample SOAP Response

Go to WSDL for DeleteFolders.

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

Errors

Sample REST Request

/ws/IMFS/GetPathInfo.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&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>Wed, 02 May 2007 13:36:41 GMT</CreatedDate>
      <SizeBytes>1000000</SizeBytes>
      <FileType>Image</FileType>
      <Metadata>

      	<MetaData FileName="F8.jpg">
              <Data Key="Height">480</Data>
	      <Data Key="MD5">JCiPH3sH4S3f/Ad93uWk+w==</Data>
              <Data Key="Width">640</Data>

        </MetaData>
      </Metadata>
      <Tags></Tags>
      <IsShared>false</IsShared>
      <ModifiedDate>Wed, 02 May 2007 13:36:41 GMT</ModifiedDate>

      <ItemID>1045632</ItemID>
   </GetPathInfo>
</response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.GetPathInfo(sessionToken, "DirTest/F8.jpg", true, false, true);

Sample SOAP Response

Go to WSDL for GetPathInfo.

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

Errors

Sample REST Request

/ws/IMFS/ListFolder.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&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>
                       <MetaData FileName="video.wmv">

                            <Data Key="BitRate">55555</Data>
                            <Data Key="Duration">59</Data>
                            <Data Key="FrameRate">4444</Data>

                            <Data Key="Height">480</Data>
                            <Data Key="Width">640</Data>
                     </MetaData>
                 </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>
             <FileTags></FileTags>

      </File>
      <File>
         <SizeBytes>1000010</SizeBytes>
         <Name>100001-somefile.txt</Name>
         <Path>DirTest/F8/100001-somefile.txt</Path>

         <CreatedDate>Wed, 02 May 2007 15:14:14 GMT</CreatedDate>
         <Metadata></MetaData>
         <FileTags></FileTags>
      </File>
   </ListFolder>

</response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.ListFolder(sessionToken, "DirTest/F8", 1, 5, "Name", false);

Sample SOAP Response

Go to WSDL for ListFolder.

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.

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.

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/MoveFiles.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFilPath=Folder/subfolder/samplefile.txt&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.MoveFiles(sessionToken, new string[]{"Folder/subfolder/samplefile.txt"}, "Folder/subfolder/DestFolder");

Sample SOAP Response

Go to WSDL for MoveFiles.

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

Sample REST Request

/ws/IMFS/MoveFolders.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFolderPath=Folder/subfolder/FolderToCopy&destFolderPath=Folder/subfolder/DestFolder

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.MoveFolders(sessionToken, new string[]{"Folder/subfolder/FolderToMove"}, "Folder/subfolder/DestFolder");

Sample SOAP Response

Go to WSDL for MoveFolders.

RenameFile

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

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/RenameFile.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&filePath=Folder/subfolder/samplefile.txt&newFileName=mynewfile.txt

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.RenameFile(sessionToken, "Folder/subfolder/samplefile.txt", "mynewfile.txt");

Sample SOAP Response

Go to WSDL for RenameFile.

RenameFolder

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

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/RenameFolder.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&folderPath=Folder/subfolder/myfolder&newFolderName=mynewfolder

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.RenameFolder(sessionToken, "Folder/subfolder/myfolder", "mynewfolder");

Sample REST XML Response

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

Sample SOAP Response

Go to WSDL for RenameFolder.

GetDownloadNodes

The GetDownloadNodes method is used to obtain the current optimum download nodes for one or more files. 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>

Errors

Sample REST Request

/ws/IMFS/GetDownloadNodes.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&filePath=My%20Folder/My%20File%201.txt&filePath=My%20Folder/My%20File%202.txt

Sample REST XML Response

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

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

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
string[] paths = new string[] { "My Folder/My File 1.txt",  "My Folder/My File 2.txt" };
string[] downloadNodes = nirvFS.GetDownloadNodes(sessionToken, paths);

Sample SOAP Response

Go to WSDL for GetDownloadNodes.

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.

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>

Errors

Sample REST Request

/ws/IMFS/GetOptimalUrls.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&filePath=My%20Folder/My%20File%201.txt&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>

   <Download>
      <FilePath>My Folder/My File 1.txt</FilePath>
      <DownloadHost>node1.nirvanix.com</DownloadHost>
      <DownloadToken>
         mIiCl6mI~LTJK3MLXek~AiW5kvHW~SoVqPWkFYR~QXu0Guc
      </DownloadToken>

      <DownloadURL>
         http://node1.nirvanix.com/mIiCl6mI~LTJK3MLXek~AiW5kvHW~SoVqPWkFYR~QXu0Guc/My%20Folder/My%20File%202.txt
      </DownloadURL>
   </Download>
</Response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
string[] paths = new string[] { "My Folder/My File 1.txt",  "My Folder/My File 2.txt" };
string[] downloadNodes = nirvFS.GetOptimalUrls(sessionToken, paths, 300, null, false);

Sample SOAP Response

Go to WSDL for GetOptimalUrls.

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.

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="UploadHost" maxOccurs="unbounded " />

           <xs:element name="UploadToken" maxOccurs="unbounded " />
         </xs:sequence>
      </xs:complexType>
   </xs:element>

</xs:schema>

Errors

Sample REST Request

/ws/IMFS/GetStorageNodeExtended.ashx?sessionToken=290cc579-bc33-4283-8701-68f5028b5adf&
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>devnode1.nirvanix.com</UploadHost>
      <UploadToken>kMHib15S~c_5IY1CphI~7cFRwvOB~E5evmH0CaL~WccWTQ_Vbu0yJGctig</UploadToken>

   </GetStorageNode>
</Response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
StorageNode storageNode = GetStorageNodeExtended(sessionToken, 450000,
 "127.0.0.1", true, "/", true, 6000, 259200);

Sample SOAP Response

Go to WSDL for GetStorageNodeExtended.

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.

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/GetStorageNode.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f&sizeBytes=1024

Sample REST XML Response

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

      <UploadHost>123node1.nirvanix.com</UploadHost>
      <UploadToken>myuploadtoken</UploadToken>
   </GetStorageNode>
</Response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
StorageNode storageNode = nirvFS.GetStorageNode(sessionToken, 1024, "10.1.1.1");

Sample SOAP Response

Go to WSDL for GetStorageNode.

SearchFileSystem

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

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/SearchFileSystem.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&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>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
SearchResults results = nirvFS.SearchFileSystem(sessionToken, myuser, Audio, 0,
100000000, new DateTime(2007, 7, 1), new DateTime(2007, 9, 1), 1000);

Sample SOAP Response

Go to WSDL for SearchFileSystem.

Sideload

The Sideload command allows a user to load remote content into their Nirvanix file system.

Input Parameters

Output Values

Sample REST Request

/ws/IMFS/Sideload.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&targetURL=http://mywebsite.com/default.html&destFilePath=mywebpages/default.html

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();
nirvFS.Sideload(sessionToken, "http://mywebsite.com/default.html", "mywebpages/default.html", null);

Sample SOAP Response

Go to WSDL for Sideload.

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.

Customer API

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

Sample REST Request

/ws/Metadata/DeleteAllMetadata.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
nirvMeta.DeleteAllMetadata(sessionToken, "Folders/subfolder/myfile.txt");

Sample REST XML Response

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

Sample SOAP Response

Go to WSDL for DeleteAllMetadata.

DeleteMetadata

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

Input Parameters

Output Values

Sample REST Request

/ws/Metadata/DeleteMetadata.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt&metadata=Width

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
MetadataTypes[] types = {MetadataType.AudioAlbum, MetadataType.AudioArtist};
nirvMeta.DeleteMetadata(sessionToken, "Folders/subfolder/myfile.txt", types);

Sample SOAP Response

Go to WSDL for DeleteMetadata.

GetMetadata

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

Input Parameters

Output Values

Sample REST Request

/ws/Metadata/GetMetadata.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&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>

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
MetadataInfo[] minfo = nirvMetadata.GetMetadata(sessionToken, "Folders/subfolder/myfile.txt");

Sample SOAP Response

Go to WSDL for GetMetadata.

SetMetadata

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

Input Parameters

Output Values

Sample REST Request

/ws/Metadata/SetMetadata.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt&metadata=Title:MySong

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
MetadataInfo m = new MetadataInfo();
m.Type = "Title";
m.Value = "MySong";
MetadataInfo[] minfo = {m};
nirvMeta.SetMetadata(sessionToken, "Folders/subfolder/myfile.txt", minfo);

Sample SOAP Response

Go to WSDL for SetMetadata.

DeleteAllTags

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

Input Parameters

Output Values

Sample REST Request

/ws/Metadata/DeleteAllTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
nirvMeta.DeleteAllTags(sessionToken, "Folders/subfolder/myfile.txt");

Sample SOAP Response

Go to WSDL for DeleteAllTags.

DeleteTags

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

Input Parameters

Output Values

Sample REST Request

/ws/Metadata/DeleteTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt&tag=foo&tag=bar

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
nirvMeta.DeleteTags(sessionToken, "Folders/subfolder/myfile.txt", new string[]{"foo", "bar"});

Sample SOAP Response

Go to WSDL for DeleteTags.

GetTags

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

Input Parameters

Output Values

Sample REST Request

/ws/Metadata/GetTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&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

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
string[] tags = nirvMeta.GetTags(sessionToken, "Folders/subfolder/myfile.txt");

Sample SOAP Response

Go to WSDL for GetTags.

SetTags

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

Input Parameters

Output Values

Sample REST Request

/ws/Metadata/SetTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt&tag=foo&tag=bar

Sample REST XML Response

<Response>
  <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
nirvFMetaSetTags(sessionToken, "Folders/subfolder/myfile.txt", new string[]{"foo", "bar"});

Sample SOAP Response

Go to WSDL for SetTags.

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

Sample REST Request

/ws/Metadata/SearchMetadata.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&

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>

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
SearchResults results = nirvMeta.SearchMetadata(sessionToken, "myuser", "Duration", "3*", 1000);

Sample SOAP Response

Go to WSDL for SearchMetadata.

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

Sample REST Request

/ws/Metadata/SearchTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&
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>

Sample SOAP Request

Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
Nirvanix.Metadata nirvMeta = new Nirvanix.Metadata();
SearchResults results = nirvMeta.SearchTags(sessionToken, "myuser", "mytag*", 1000);

Sample SOAP Response

Go to WSDL for SearchTags.

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 MFS 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.

Customer API

ListHostedItems

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

Input Parameters

Output Values

Sample REST Request

/ws/Sharing/ListHostedItems.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&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>

Sample SOAP Request

Nirvanix.Sharing nirvSharing = new Nirvanix.Sharing();
nirvSharing.ListHostedItems(sessionToken, 1, 10);

Sample SOAP Response

Go to WSDL for ListHostedItems.

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.

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

Input Parameters

Output Values

Sample REST Request

/ws/Sharing/CreateHostedItem.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&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>

Sample SOAP Request

Nirvanix.Sharing nirvSharing = new Nirvanix.Sharing();
string downloadLink = nirvSharing.CreateHostedItem(sessionToken, "Folder/subfolder/samplefile.txt");

Sample SOAP Response

Go to WSDL for CreateHostedItem.

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

Sample REST Request

/ws/Sharing/RemoveHostedItem.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&sharePath=Folder/subfolder/samplefile.txt

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Sharing nirvSharing = new Nirvanix.Sharing();
nirvSharing.RemoveHostedItem(sessionToken, "Folder/subfolder/samplefile.txt");

Sample SOAP Response

Go to WSDL for RemoveHostedItem.

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

Sample REST Request

/ws/Image/Resize.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&srcFilePath=
Folder/subfolder/samplefile.jpg&destFilePath=MyResizedImages/samplefileResized.gif

&width=320&height=640&callbackURL=http://mywebsite.com/mypage.aspx

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Nirvanix.Image nirvImage = new Nirvanix.Image();
nirvImage.Resize(sessionToken, " Folder/subfolder/samplefile.jpg",
"MyResizedImages/samplefileResized.gif", 320, 640, "http://mywebsite.com/mypage.aspx");

Sample SOAP Response

Go to WSDL for Resize.

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

Sample REST Request

/ws/Image/RotateFlip.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&srcFilePath=
Folder/subfolder/samplefile.jpg&destFilePath=MyNewImages/samplefileRotated.gif
&rotate=Rotate90&flip=FlipHorizontal&callbackURL=http://mywebsite.com/mypage.aspx

Sample REST XML Response

<Response>
   <ResponseCode>0</ResponseCode>

</Response>

Sample SOAP Request

Nirvanix.Image nirvImage = new Nirvanix.Image();
nirvImage.RotateFlip(sessionToken, " Folder/subfolder/samplefile.jpg",
"MyNewImages/samplefileRotated.gif", RotateType.Rotate90, FlipType.FlipHorizontal, 
"http://mywebsite.com/mypage.aspx");

Sample SOAP Response

Go to WSDL for RotateFlip.

Download Component

The download component allows users of the Nirvanix Internet Media File System (IMFS) 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.

Customer API

Because of the global caching node architecture, downloading a file from IMFS is a two-step process. First the user must obtain the download location for each file path from the IMFS 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.

HTTP Get

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.

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 Media File System (IMFS). An HTTP upload interface is also provided.

Customer API

AppendFile

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.

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

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

The HTTP protocol allows a multipart/form-data POST to upload files using "/Upload.ashx". Please refer to this section for more details on multipart/form-data POST. Once the HTTP post is complete the response is a summary of the upload. Optionally the user can be forwarded to another URL. If the user is forwarded, some additional parameters are appended to the forwarding URL. Another option is to specify a callback URL. This URL is invoked when the file has been completely uploaded.

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

The actual IMFS destination of upload files is destFolder/<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 actual destination IMFS 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 forward the user (see Forwarding URL section below.)

<Response>

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

Forwarding URL

If a forwardingUrl is passed it must be able to contain a 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.

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.

HTTP Update

The http protocol also allows a multipart/form-data POST to update an existing file using "/Upload.ashx" in conjunction with the "Content-Range" header. Please refer to this section for more details on multipart/form-data POST. Because this operation overwrites an existing file, the upload token must be obtained by calling the method GetStorageNodeExtended with the parameter "fileOverwrite" set to true. Once the HTTP post is complete the response is a summary of the update request. However, since the processing time may be much greater than the transfer time (for example, updating 1MB of a 4GB file), the user is notified of the completion of the update asynchronously via the required callback URL. Also because of the asynchronous nature of this call, we highly recommend that the MD5 hash of the updated file is specified to ensure the integrity of the update. If the MD5 does not match after assembling the modified version, the update fails and the original version of the file remains intact.

Input Parameters

Output Values

HTTP Update either responds with the following XML, or it forward the user (see Forwarding URL section below.)

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

   <BytesUploaded>105450</BytesUploaded>
</Response>

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. back to top

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.

Customer API

NOTE: SetAccountPassword method will be deprecated with release 1.0.3.7 and will be replaced with more secure and fully functional methods shortly after.

CreateChildAccount

The CreateChildAccount command creates a child account with the provided username, password, and contact info under a specific Application Key. The provided Session Token must be from the parent account login. The username must be unique under the Application Key associated with the session token. This command is exposed as a web service.

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is also 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>

DeleteChildAccount

The DeleteChildAccount command deletes the child account with the provided username. The provided Session Token must be from the parent account login and the Application Key provided must be from an application owned by that parent 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. This command is exposed as a web service.

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

Input Parameters

Output Values

A Response Code is always returned. If an error occurred, an Error Message is also 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>

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. This command is exposed as a web service.

Input Parameters

Output Values

A Response Code is always returned. A successful execution will return the feature name and usage amount. 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="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>

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. This command is exposed as a web service.

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>

SetAccountLimits

The SetAccountLimits command sets the limits for the provided username under the provided Application Key. The Session Token must belong to a Parent Account for the username. A Response Code will be returned. This command is exposed as a web service.

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>

GetAccountInfo

The GetAccountInfo command gets the account details for the account associated with the session token. A Response Code will be returned, as well as a list of information. This command is exposed as a web service.

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:element ref="UserName" minOccurs="0"/>
                   <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 name="responseCode">
         <xs:simpleType>
              <xs:restriction base="xs:integer" />

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

          <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:schema>

SetAccountInfo

The SetAccountInfo command changes the account details for the provided session token.

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>

Errors

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 Parent Account for the username. A Response Code will be returned. This command is exposed as a web service.

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>

GetAccountNotes

The GetAccountNotes 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 Parent Account for the username. A XML document will be returned. This command is exposed as a web service.

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>

GetStorageUsage

The GetStorageUsage command returns the total storage usage for the account associated with the session token. A Response Code will be returned, as well as the total storage in bytes. This command is exposed as a web service.

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=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&username=mychilduser

Sample REST XML Response

<Response>

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

Sample SOAP Request

Nirvanix.Accounting nirvAcct = new Nirvanix.Accounting();
long storageUsage = nirvAcct.GetStorageUsage(sessionToken, "mychilduser");

Sample SOAP Response

Go to WSDL for GetStorageUsage

ListChildAccounts

The ListChildAccounts method will retrieve the list of child accounts associated with the specified master account.

Input Parameters

Output Values

Sample REST Request

/ws/Accounting/ListChildAccounts.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&pageNumber=1&pageSize=500

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Accounting nirvAcct = new Nirvanix.Accounting();
string[] users = nirvAcct.ListChildAccounts(sessionToken, 1, 500);

Sample SOAP Response

Go to WSDL for 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.

Customer API

Transcode

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

Input Parameters

Output Values

Sample REST Request

/ws/Audio/Transcode.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFilePath=mysong.mp3&destFilePath=mynewsong.wav&numberOfFrames=10000&bitRate=192

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Audio nirvAudio = new Nirvanix.Audio();
string[] options = {"numberOfFrames:1000"};
nirvAudio.Transcode(sessionToken, "mysong.mp3", "mysong.wav", null, options);

Sample SOAP Response

Go to WSDL for Transcode

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.

Customer API

PresetTranscode

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

Input Parameters

Output Values

Sample REST Request

/ws/Video/PresetTranscode.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&
srcFilePath=myvideo.mpg&preset=H263+FLV+Medium&scaleWidth=640&scaleHeight=480

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Video nirvVideo = new Nirvanix.Video();
string[] options = {"scaleWidth:300", "scaleHeight:400"};
nirvVideo.Transcode(sessionToken, "myvideo.mpg", "myvideo.mov", null, "H263 FLV Medium", options);

Sample SOAP Response

Go to WSDL for Preset Transcode

Transcode

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

Input Parameters

Output Values

Sample REST Request

/ws/Video/Transcode.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFilePath=myvideo.mpg&numberOfFrames=10000&frameRate=24&width=640&height=480&aspectRatio=
1.33&audioFreq=44100

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Video nirvVideo = new Nirvanix.Video();
string[] options = {"width:300", "height:400"};
nirvVideo.Transcode(sessionToken, "myvideo.mpg", "myvideo.mov", null, options);

Sample SOAP Response

Go to WSDL for Transcode

ExtractFrames

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

Input Parameters

Output Values

Sample REST Request

/ws/Video/ExtractFrames.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFilePath=myvideo.mpg&destFolderPath=myFrameFolder&numberOfFrames=10000&frameName=MyFrame

Sample REST XML Response

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

Sample SOAP Request

Nirvanix.Video nirvVideo = new Nirvanix.Video();
string[] options = {"width:300", "height:400", "frameName:MyFrame", "StartTimeOffset:10.5"};
nirvVideo.ExtractFrames(sessionToken, "myvideo.mpg", "myFrameFolder", null, options);

Sample SOAP Response

Go to WSDL for ExtractFrames

Virtual URL Hosting

Virtual URL Hosting is a method whereby a Nirvanix customer can choose to allow Nirvanix control of an internet-accessible sub-domain (or in rare cases, a root domain). This enables Nirvanix URLs to be replaced with the new address, thereby masking the Nirvanix name from various internet requests.

For example, if Joe owns the domain "joe77.com", Joe can build the NS-Rec for "storage.joe77.com", pointing at the Nirvanix domain servers. Nirvanix will create CNAME records for "storage.joe77.com". This will allow "services.storage.joe77.com" to be used to in place of "services.nirvanix.com", as well as all other Nirvanix sub-domains.

Another option is using the Authoritative DNS to set a domain root as a Virtual URL. For example, if Joe owned the domain "storage77.com", Joe could use the Authoritative DNS to point to the Nirvanix Nameservers. This will allow "services.storage77.com" to be used in place of "services.nirvanix.com". However, Joe does not retain control over sub-domains for "storage77.com". For example, Joe cannot have "www.storage77.com" resolve to a web site.

Joe can now present masked URLs to his clients, and never show the nirvanix.com name. Joe can manage URLs to allow client uploads, downloads, and Web Services access that all contain his sub-domain, without the need to manage CNAME records for the Nirvanix servers.

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.

Glossary

NS Record (NS-Rec) - Used to delegate a portion of your name space (ex: campus1.domain.com) to external name servers. You cannot use NS records for your base domain name (ex: domain.com) as the DNS Manager creates these records for you automatically. If you want to delegate a portion of your name space to another server, enter the name space as the FQDN, select NS record type and enter the Name Server responsible for this name space in the Server Name field. (i.e. pointing storage.joe77.com to the Nirvanix DNS servers so that they control the *.storage.joe77.com zone)

Authoritative DNS - The DNS server responsible for controlling the address information for an entire zone. (i.e. storage77.com)

CNAME - An alias within a DNS referencing a (sub) domain to a separate (sub) domain’s IP address associations. (i.e. Referencing node1.storage.joe77.com to node1.nirvanix.com)

Mapped Zone (new concept) - A domain (joe77.com) or sub-domain (storage.joe77.com) that has been properly associated within the Nirvanix DNS, including the NS-Record and CNAMEs and HAS been mapped to a specific Application or Child Account. (i.e. storage.joe77.com pointing to nirvanix.com\JoeApp1\JoeUser1).

Default Mapping (new concept) - A domain (storage77.com) or sub-domain (storage.joe77.com) that has been properly associated within the Nirvanix DNS, including the NS-Record and CNAMEs but HAS NOT been mapped to a specific Application or Child Account. (i.e. storage.joe77.com pointing to nirvanix.com).

Virtual URL - A URL that has been passed to Nirvanix but does not carry the "nirvanix.com" domain. Rather, this URL is a virtual reference of an NS-Record or Authoritative DNS assigned to us by a customer.

Managing Virtual URLs

Activating a Virtual URL is a two-step process. After a URL is selected, an NS-Record must be created, with the Nameservers pointing to the Nirvanix Nameservers. The sub-domain must also be registered with Nirvanix through the Nirvanix Management Portal.

The customer must create an NS-Rec for a sub-domain before the Virtual URL will function correctly. The Nameservers for this NS-Rec must be set to the Nirvanix Nameservers. The tools to work with NS-Records and the DNS are provided externally from Nirvanix, and vary depending on how the URL is hosted. The addresses for the Nirvanix Nameservers are provided on the Virtual URL Administration page in the Nirvanix Management Portal.

For example, if Joe owns the domain "joe77.com", Joe can build the NS-Rec for "storage.joe77.com". Once the NS-Rec exists, Joe sets the Nameservers to point to the Nirvanix Nameservers. After the appropriate amount of DNS propagation time has elapsed, "anything.storage.joe77.com" will be controlled by the Nirvanix DNS servers.

All Virtual URLs must be registered through the Nirvanix Management Portal. Login to the portal (nmp.nirvanix.com) and browse to the Virtual URLs section under Applications. At this page, you are presented with the following:

1. Pricing for Virtual URLs
2. Nirvanix Nameservers
3. An area to create new Virtual URLs
4. A list of existing Virtual URLs that can be deleted, or have their mappings reassigned

This page provides all the tools needed to register and customize a Virtual URL with Nirvanix.

Propagation Times

New Virtual URLs require 24 - 72 hours for the DNS to propagate completely.

Mappings can be reassigned with only a 5 - 10 minute propagation delay.

Virtual URLs that are deleted will fail within 5 - 10 minutes. The URL will no longer resolve to the Nirvanix Nameservers after the 24 - 72 hour propagation time has elapsed.

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. The Virtual URL can be re-created. Normal setup charges would apply.

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 upload and download links take this form:
node1.nirvanix.com/<Application Name>/<Account Username>/Path to File

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

However, if Joe has the Virtual URL "storage.joe77.com" mapped to an Application, that Application name should not be included in the URL. This might be a sample URL with Application Mapping:
http://node1.storage.joe77.com/Account_Username/File_in_the_root_directory.txt

Similarly, if Joe has the Virtual URL "storage.joe77.com" mapped to an Account, the Application Name and Account Username would not be included. This link might look like this:
http://node1.storage.joe77.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, Joe has the following

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

Joe can use the following URL to login "Child1"
http://services.storage.joe77.com/ws/Authentication/Login.ashx

However "Child 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 if 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 IMFS 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.

Miscellaneous

• A Virtual URL can only have one mapping. However, a single Application or Account can have several Virtual URLs mapped to it.
• All URLs with Records pointing to Nirvanix Nameservers must be registered through the Nirvanix Management Portal. This restriction prevents URL spoofing.

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.

Customer API

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.

HTTP Update Examples

For each of the examples below, assume the existing file is 10 bytes long and has the following bytes before the update request:

0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09

Example 1: updating bytes 1 through 5

-----------------------------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="fileMD5"\r\n
\r\n
+XxdKZQb+xsv2rCHSQargg==\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackUrl"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 0-4/5\r\n
\r\n
0xf0 0xf1 0xf2 0xf3 0xf4\r\n
-----------------------------170062046428149--\r\n
  

Updated file content:

0x00 0xf1 0xf2 0xf3 0xf4 0xf5 0x06 0x07 0x08 0x09

Example 2: updating bytes 1 through 5 and byte 9

-----------------------------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="fileMD5"\r\n
\r\n
+XxdKZQb+xsv2rCHSQargg==\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackUrl"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 1-5/10\r\n
\r\n
0xf1 0xf2 0xf3 0xf4 0xf5\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent2"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 9-9/10\r\n
\r\n
0xf9\r\n
-----------------------------170062046428149--\r\n
  

Updated file content:

0x00 0xf1 0xf2 0xf3 0xf4 0xf5 0x06 0x07 0x08 0xf9

Example 3: appending bytes 10 through 15

-----------------------------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="fileMD5"\r\n
\r\n
+XxdKZQb+xsv2rCHSQargg==\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackUrl"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 10-15/16\r\n
\r\n
0x0A 0x0B 0x0C 0x0D 0x0E 0x0F\r\n
-----------------------------170062046428149--\r\n
  

Updated file content:

0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0A 0x0B 0x0C 0x0D 0x0E 0x0F

Example 4: updating bytes 1 through 4, truncating bytes 5-9

-----------------------------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="fileMD5"\r\n
\r\n
+XxdKZQb+xsv2rCHSQargg==\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackUrl"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 1-4/5\r\n
\r\n
0xf1 0xf2 0xf3 0xf4\r\n
-----------------------------170062046428149--\r\n
  

Updated file content:

0x00 0xf1 0xf2 0xf3 0xf4

Example 5: updating entire file (Content-Range is optional in this case)

-----------------------------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="fileMD5"\r\n
\r\n
+XxdKZQb+xsv2rCHSQargg==\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackUrl"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
\r\n
0xf0 0xf1 0xf2 0xf3 0xf4\r\n
-----------------------------170062046428149--\r\n
  

Updated file content:

0xf0 0xf1 0xf2 0xf3 0xf4

Example 6: invalid request with unspecified gap

-----------------------------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="fileMD5"\r\n
\r\n
+XxdKZQb+xsv2rCHSQargg==\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackUrl"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 11-15/16\r\n
\r\n
0x0B 0x0C 0x0D 0x0E 0x0F\r\n
-----------------------------170062046428149--\r\n
  

Request is invalid because byte 10 is not specified.

Example 7: invalid request with overlapping byte ranges

-----------------------------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="fileMD5"\r\n
\r\n
+XxdKZQb+xsv2rCHSQargg==\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="callbackUrl"\r\n
\r\n
http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 8-9/16\r\n
\r\n
0xF8 0xF9\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent2"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 9-15/16\r\n
\r\n
0x19 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F\r\n
-----------------------------170062046428149--\r\n
  

Request is invalid because byte 9 is specified in both ranges.