Nirvanix Web Services API Developer's Guide v1.

0
Release 1.1.4.5
1/17/2007

Getting Started: An introduction to key concepts
r

What is an Internet Media File System? When to use an IMFS?

Getting Started: An introduction to key concepts
back to top

r

Web Services Overview
r

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

Calling Nirvanix Web Services
■ ■ ■

SOAP REST HTTP GET

r

The Nirvanix Media Filesystem Overview

Understanding Nirvanix Namespaces
r r r r r r r r r r

Why are Namespaces important? Authentication Namespace Account Management Namespace IMFS Namespace Metadata Namespace Sharing Namespace Image Namespace Transfer Namespace Audio Namespace Video Namespace

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

back to top

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

Setting up Nirvanix MFS
r

Master Accounts

Creating Master Accounts Creating Child Accounts Deleting Child Accounts Managing Child Account Information

r

Child Accounts
■ ■ ■

r

Authentication

Accessing Nirvanix MFS
r r r

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

Creating Directories or Folders Manipulating Files and Folders Uploading Files
■ ■

SOAP HTTP Upload Request URL Metadata

r

Downloading Files

r

Nirvanix Extensibility

r r

Tags Sharing

Authentication Namespace
r

Customer API
■ ■ ■ ■ ■

Login LoginProxy Logout ChangePassword SetChildAccountPassword

Calling Nirvanix Web Services

Internet Media File System (IMFS) Namespace
r

Customer API
■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■

Common Errors CopyFiles CopyFolders CreateFolders DeleteFiles DeleteFolders ListFolder MoveFiles MoveFolders RenameFile RenameFolder GetDownloadNodes GetOptimalUrls GetStorageNodeExtended GetStorageNode SearchFileSystem Sideload

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-4c22a8e0-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 user's 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-210d45df-85df-b48b277c13c5</ErrorMessage> </Response>

Metadata Namespace
r

Customer API
■ ■ ■ ■ ■ ■ ■ ■ ■ ■

DeleteAllMetadata DeleteMetadata GetMetadata SetMetadata DeleteAllTags DeleteTags GetTags SetTags SearchMetadata SearchTags

Sharing Namespace
r

Customer API
■ ■ ■

ListHostedItems CreateHostedItem RemoveHostedItem

Image Namespace
r r

Resize RotateFlip

HTTP GET
See section 9.3of RFC 2616 for information about GET and partial GET. back to top

Download Component
r

Customer API

HTTP Get

The Nirvanix Media File System Overview

Transfer Namespace
r

Customer API
■ ■ ■

AppendFile UploadFile HTTP Upload

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

Accounting Namespace
r

Customer API
■ ■

Understanding Nirvanix Namespaces
Why are Namespaces important?

CreateChildAccount DeleteChildAccount

■ ■ ■ ■ ■ ■ ■ ■

GetAccountUsage GetAccountLimits SetAccountLimits GetAccountInfo SetAccountInfo GetAccountNotes SetAccountNotes ListChildAccounts

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

Audio Namespace
r

Customer API

Authentication Namespace
http://services.nirvanix.com/ws/Authentication.asmx?WSDL back to top

Transcode

Video Namespace
r

Customer API
■ ■

Transcode ExtractFrames

Account Management Namespace
http://services.nirvanix.com/ws/Accounting.asmx?WSDL back to top

Virtual URL Hosting
r r r r r

Glossary Managing Virtual URLs Propagation Times Mapped Zones Generating Transfer Paths for Mapped Virtual URLs Using Web Services with Virtual URLs Miscellaneous

IMFS Namespace
http://services.nirvanix.com/ws/IMFS.asmx?WSDL back to top

r

Metadata Namespace
http://services.nirvanix.com/ws/Metadata.asmx?WSDL back to top

r

Exception Framework
r

Customer API

Sharing Namespace
http://services.nirvanix.com/ws/Sharing.asmx?WSDL back to top

Appendices
r r r

Date Formats Country Codes for Web Services HTTP Update Examples

Image Namespace
http://services.nirvanix.com/ws/Image.asmx?WSDL back to top

Transfer Namespace
http://node1.nirvanix.com/ws/Transfer.asmx?WSDL back to top

Audio Namespace
http://services.nirvanix.com/ws/Audio.asmx?WSDL back to top

Video Namespace
http://services.nirvanix.com/ws/Video.asmx?WSDL back to top

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.

back to top

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

Child Accounts
Creating Child Accounts
Child accounts are created via a Web Services call. The CreateChildAccount command can be used to create individually managed enduser 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. back to top

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

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

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

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 precede any multipart form data which contains file content. This allows us to verify security before attempting to accept the upload, if this is not done you will receive an error. 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 upload 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.
Sample HTTP multipart/form-data Upload

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

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> Example: Application Name: MyApp Username: MyUser1 Login Session Token: 6db4715f-1e5c-4ef5-9cd6-d97bc947bf5d Private File Path: /folder1/privateFile.txt Hosted File Path: /folder1/folder2/hostedFile.txt Transfer Node: node1.nirvanix.com Private File URL: http:// node1.nirvanix.com/6db4715f-1e5c-4ef5-9cd6-d97bc947bf5d/MyApp/MyUser1/folder1/privateFile.txt Hosted File URL: http:// node1.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt Optionally, you can also specify the download content disposition with the query parameter "disposition". Valid values for this parameter are "inline" and "attachment". Example: http://node1.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt?disposition=inline http://node1.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt?disposition=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. Example: http://services.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt?disposition=attachment is redirected to http://node1.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt?disposition=attachment 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

back to top

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

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

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

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 Parameter appKey userName password Output Values Name ResponseCode SessionToken Description A result code with the status of the login. If the result is 0 the method was successful. A token that represents the logged in user. Sample Value 0 54592180-7060-4D4B-BC74-2566F4B2F943 Description The application key that contains the user to be logged in. The account name to log in with. The password for the account. Required/Optional Required Required Required

Sample REST Request /ws/Authentication/Login.ashx?appKey=8da051b0-a60f-4c22a8e0-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 Parameter appKey userName password consumerIP Output Values Name ResponseCode SessionToken Description A result code with the status of the login. If the result is 0 the method was successful. A token that represents the logged in user. Sample Value 0 54592180-7060-4D4B-BC74-2566F4B2F943 Description The application key that contains the user to be logged in. The account name to log in with. The password for the account. The consumer's IP address. Required/Optional Required Required Required Required

Sample REST Request /ws/Authentication/LoginProxy.ashx?appKey=8da051b0-a60f-4c22a8e0-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 Parameter sessionToken Output Values Name ResponseCode Description A result code with the status of the rename. If the result is 0 the method was successful. Sample Value 0 Description The session token that represents the user to be logged out. Required/Optional Required

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 Parameter appKey userName oldPassword newPassword Output Values Name ResponseCode Description A result code with the status of the password change. If the result is 0 the method was successful. Sample Value 0 Description The application key that contains the user to change. The account name to change. The old password for the account. The new password to change to. Required/Optional Required Required Required Required

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 Parameter appKey userName password childAccountUsername childAccountPass Output Values Name ResponseCode Description A result code with the status of the set password. If the result is 0 the method was successful. Sample Value 0 Description The application key that contains the user to change. The master account name. The password for the master account. The child account name to set the password. The child account password to set to. Required/Optional Required Required Required Required Required

Sample REST Request /ws/Authentication/SetChildAccountPassword.ashx?appKey=8da051b0-a60f-4c22a8e0-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. back to top

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: Absolute: /8da051b0-a60f-4c22-a8e0-d9380edafa6f/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. 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
Code 100 70009 70010 70102 80006 80101 Description Missing required parameters Path too long File/Folder name too long Invalid path character Session not found Invalid session token Details Occurs when one or more required parameters is missing. Occurs when the total length of a relative path exceeds the maximum length of 512 characters. Occurs when a file or folder name exceeds the maximum length of 256 characters. Occurs when any path contains illegal characters. Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. Occurs when the session token is malformed.

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. Input Parameters Parameter sessionToken srcFilePath destFolderPath Output Values Name ResponseCode Description A result code with the status of the copy. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the file to be copied. More than one file can be specified using a multiple instance of this parameter. The path to the folder where the items will be copied to. The name of the item is not included in the destination folder. Required/Optional Required Required Required

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. Input Parameters Parameter sessionToken srcFolderPath destFolderPath Output Values Name ResponseCode Description A result code with the status of the copy. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The folders to be copied. More than one folder may be specified using multiple instances of this parameter. The path to the folder where the items will be copied to. Required/Optional Required Required Required

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 Parameter sessionToken folderPath Description A valid session token for the user. The path to the folder to be created. More than one folder may be specified using multiple instances of this parameter. Required/Optional Required Required

Output Values Name ResponseCode Description A result code with the status of the folder create. If the result is 0 the method was successful. Sample Value 0

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 Parameter sessionToken filePath Description A valid session token for the user. The path to the file to be deleted. One or more files may be specified using multiple instances of this parameter. Required/Optional Required Required

Output Values Name ResponseCode Description A result code with the status of the file delete. If the result is 0 the method was successful. Sample Value 0

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 Parameter sessionToken folderPath Description A valid session token for the user. The path to the folder to be deleted. One or more folders may be specified using multiple instances of this parameter. Required/Optional Required Required

Output Values Name ResponseCode Description A result code with the status of the folder delete. If the result is 0 the method was successful. Sample Value 0

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 Nirvanix.IMFS nirvFS = new Nirvanix.IMFS(); nirvFS.DeleteFolders(sessionToken, new string[] {"Folders/subfolder"}); Sample SOAP Response Go to WSDL for DeleteFolders.

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 Parameter sessionToken folderPath pageNumber pageSize sortCode sortDescending showMetadata showTags Output Values Name ResponseCode ListFolder ErrorMessage Errors Code 70001 Description Folder not found Details Occurs if the folder does not exist. Description A result code with the status of the move. The code will be 0 if the method is successful or one of the error codes below if an error occurs. The requested page of folder content if the response code is 0. The error message if the response code is not 0. Description A valid session token for the user. The path to the folder to be listed. If not specified, the logged in accounts root folder will be listed. The page number to list. The size of the page to return. Required/Optional Required Optional Required Required

The sorting criteria. Must be one of the following: Name, CreatedDate, SizeBytes, FileType. By default, listing will be sorted by Name. Also regardless of the sorting criteria, all folders will Optional be grouped together and all files will be grouped together. Flag to indicate whether the sorting should be in descending order. Set to true if descending order is desired. Flag to indicate whether metadata is returned. Flag to indicate whether tags are returned. Optional Optional Optional.

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. Input Parameters Parameter sessionToken srcFilePath destFolderPath Output Values Name ResponseCode Description A result code with the status of the move. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. Required/Optional Required

The path to the file to be move. More than one file can be specified using multiple instances of Required this parameter. The path to the folder where the items will be moved to. The name of the item is not included in the destination folder. Required

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. Input Parameters Parameter sessionToken srcFolderPath destFolderPath Output Values Name ResponseCode Description A result code with the status of the move. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The folders to be moved. More than one folder may be specified using multiple instances of this parameter. The path to the folder where the items will be moved to. Required/Optional Required Required Required

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 Parameter sessionToken filePath newFileName Output Values Name ResponseCode Description A result code with the status of the rename. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the file to be renamed. The name of the new file. Required/Optional Required Required Required

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 Parameter sessionToken folderPath newFolderName Output Values Name ResponseCode Description A result code with the status of the rename. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the folder to be renamed. The name of the new folder. Required/Optional Required Required Required

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 Parameter sessionToken filePath Description A valid session token for the user. The path to the file to download. More than one may be specified using multiple instances of this parameter. Required/Optional Required Required

Output Values Name ResponseCode DownloadNode ErrorMessage REST XSD <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> Description A result code with the status of the request. The code will be 0 if the method is successful or one of the error codes below if an error occurs. The corresponding download nodes if the response code is 0. The error message if the response code is not 0.

<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 Code 100 70002 70009 70010 70102 80006 80101 Description Missing required parameters File not found Path too long File/Folder name too long Invalid path character Session not found Invalid session token Details Occurs when one or more required parameters is missing. Occurs if any of the files does not exist. Occurs when the total length of a relative path exceeds the maximum length of 512 characters. Occurs when a file or folder name exceeds the maximum length of 256 characters. Occurs when any path contains illegal characters. Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. Occurs when the session token is malformed.

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 Parameter sessionToken filePath expiration consumerIP ipRestricted Description A valid session token for the user. The path to the file to download. More than one may be specified using multiple instances of this parameter. The links time to expiration in seconds. The IP address of the web client which the link is best suited for. Boolean determining whether the link is restricted to the consumerIP. Required/Optional Required Required Required Optional Optional

Output Values Name ResponseCode Download ErrorMessage REST XSD <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> Description A result code with the status of the request. The code will be 0 if the method is successful or one of the error codes below if an error occurs. The corresponding download link information if the response code is 0. The error message if the response code is not 0.

<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 Code 100 70005 70009 70010 70102 80006 80101 Description Missing required parameters Invalid path Path too long File/Folder name too long Invalid path character Session not found Invalid session token Details Occurs when one or more required parameters is missing. Occurs if any of the files do not exist or a if a folder was passed in. Occurs when the total length of a relative path exceeds the maximum length of 512 characters. Occurs when a file or folder name exceeds the maximum length of 256 characters. Occurs when any path contains illegal characters. Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. Occurs when the session token is malformed.

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 Parameter sessionToken sizeBytes consumerIP ipRestricted destFolderPath fileOverwrite firstByteExpiration lastByteExpiration Output Values Name ResponseCode UploadHost UploadToken ErrorMessage 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 Code 100 70009 70010 70102 80006 80101 Description Missing required parameters Path too long File/Folder name too long Invalid path character Session not found Invalid session token Details Occurs when one or more required parameters is missing. Occurs when the total length of a relative path exceeds the maximum length of 512 characters. Occurs when a file or folder name exceeds the maximum length of 256 characters. Occurs when any path contains illegal characters. Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. Occurs when the session token is malformed. Description A result code with the status of the request. The code will be 0 if the method is successful or one of the error codes below if an error occurs. The server to upload to. An access token to pass into one of the upload methods when performing an upload. The error message if the response code is not 0. Description A valid session token for the user. The size of the file to be uploaded in bytes. The IP address for the machine that will make the upload. The default is the IP address of the machine making this call. True if the upload token should be restricted to the consumerIP. The default is true. The folder path that any uploads using the provided upload token must be uploaded into. True if a file with the same name in the destination folder should be overwritten by a file uploaded using the upload token. If this value is false, name collisions will result in an upload error. The default is false. Required/Optional Required Required Optional Optional Required Optional

The number of seconds the upload token has until the first byte of an upload is transferred. Optional The default value is for 10 minutes. The number of seconds the upload token has until an upload is completed. The default value is for 3 days. Optional

Sample REST Request /ws/IMFS/GetStorageNodeExtended.ashx?sessionToken=290cc579-bc33-42838701-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 Parameter sessionToken sizeBytes Output Values Name ResponseCode UploadHost AccessToken Description A result code with the status of the rename. If the result is 0 the method was successful. The server to upload to. An access token to pass into one of the upload methods. Sample Value 0 node1.nirvanix.com ASDF123DASD Description A valid session token for the user. The size of the file to be uploaded in bytes. Required/Optional Required Required

Sample REST Request /ws/IMFS/GetStorageNode.ashx?sessionToken=8da051b0-a60f-4c22a8e0-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); 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 Parameter sessionToken username searchTerm fileType minFileSize maxFileSize minCreatedDate Description A valid session token for the user. The username of the account to be searched. The search string to look for files and folders. The '*' character may be used at the end of the string to support wild card searches. The file type to search for. Valid types are 'Unassigned', 'Document', 'Executable', 'Audio', 'Video', 'Image'. Passing 'null' means to allow any file type in the search results. The minimum file size to search for. Should be set to 0 when searching for folders. The maximum file size to search for. Should be set to 0 when searching for folders. The minimum created date for files. Required/Optional Required Required Required Optional Required Required Required

maxCreatedDate maxResults Output Values Name ResponseCode SearchCount CreatedDate FileType IsFile ItemName ItemPath SizeBytes

The maximum created date for files. The maximum number of results to return

Required Required

Description A result code with the status of the search. If the result is 0 the method was successful. The number of results returned in the search. The date the item was added to the file system. The type of file. A flag to indicate whether the item is a file or folder. The name of the file or folder. The fully qualified path to the file or folder. The size of the file. 0 if the item is a folder.

Sample Value 0 15 9/1/2007 Audio True Myimage.jpg MyFolder/MyImage.jpg 123456

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 Parameter sessionToken targetURL destFilePath callbackURL Output Values Name ResponseCode Description A result code with the status of the sideload. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The URL to retrieve the remote content from. The Nirvanix file system path to store the remote content. The URL to be invoked by NWS when the sideload operation has been completed. Required/Optional Required Required Required Required

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

Metadata Namespace
Nirvanix Web Services implements the industry standard REST and SOAP protocols allowing end users to upload, copy, move, and delete files and folders. Furthermore, end users can retrieve a listing of their files and also associate user-defined tags and metadata. Metadata refers to a specific type of information about a specific type of file. Nirvanix Web Services supports any type of metadata. back to top

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. Please note that the MD5 metadata type will NOT be removed with this call. Input Parameters Parameter sessionToken path Output Values Name ResponseCode Description A result code with the status of the metadata delete. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the file to have all metadata removed. Required/Optional Required Required

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. Input Parameters Parameter sessionToken path metadata Description A valid session token for the user. The path to the file to have all metadata removed. The types of metadata to be deleted. More than one type may be specified using multiple instances of this parameter. Required/Optional Required Required Required

Output Values Name ResponseCode Description A result code with the status of the metadata delete. If the result is 0 the method was successful. Sample Value 0

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. Input Parameters Parameter sessionToken path Output Values Name ResponseCode Description A result code with the status of the metadata get. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the file to have all metadata retrieved. Required/Optional Required Required

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. Input Parameters Parameter sessionToken path metadata Description A valid session token for the user. The path to the file to have the metadata set. The metadata to be set. The format is : More than one metadata may be specified using multiple instances of this parameter. The maximum length for the metadata type is 100 characters. The maximum length for the metadata value is 400 characters. The following characters are not allowed to specified in metadata: * | Required/Optional Required Required Required

Output Values Name ResponseCode Description A result code with the status of the metadata set. If the result is 0 the method was successful. Sample Value 0

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. Input Parameters Parameter sessionToken path Output Values Name ResponseCode Description A result code with the status of the tag delete. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the file to have all tags removed. Required/Optional Required Required

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. Input Parameters Parameter sessionToken path tag Description A valid session token for the user. The path to the file to have all metadata removed. The tags to be deleted. More than one type may be specified using multiple instances of this parameter. Required/Optional Required Required Required

Output Values Name ResponseCode Description A result code with the status of the tag delete. If the result is 0 the method was successful. Sample Value 0

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. Input Parameters Parameter sessionToken path Output Values Name ResponseCode Description A result code with the status of the tag get. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the file to have all tags retrieved. Required/Optional Required Required

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. Input Parameters Parameter sessionToken path tag Description A valid session token for the user. The path to the file to have all metadata removed. The tags to be set. One or more tags may be specified using multiple instances of this parameter. This does allow for duplicate tags so if you specify multiple instances of the same tag, you will get all occurrences of that tag. The following characters are not allowed to specified in a tag: * | Required/Optional Required Required Required

Output Values Name ResponseCode Description A result code with the status of the tag set. If the result is 0 the method was successful. Sample Value 0

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 Parameter sessionToken username searchKey searchTerm maxResults Description A valid session token for the user. The username of the account to be searched. The metadata search key. Example: Duration. The search string to look for files and folders. The '*' character may be used at the end of the string to support wild card searches. Wildcards are not supported if the searchKey is MD5. The maximum number of results to return Required/Optional Required Required Required Required Required

Output Values Name ResponseCode SearchCount CreatedDate FileType IsFile ItemName ItemPath SizeBytes Description A result code with the status of the search. If the result is 0 the method was successful. The number of results returned in the search. The date the file was added to the file system. The type of file. A flag to indicate whether the item is a file or folder. The name of the file or folder. The fully qualified path to the file or folder. The size of the file. 0 if the item is a folder. Sample Value 0 15 9/1/2007 Audio True Myimage.jpg MyFolder/MyImage.jpg 123456

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 Parameter sessionToken username searchTerm maxResults Description A valid session token for the user. The username of the account to be searched. The search string to look for in the tags. The '*' character may be used at the end of the string to support wild card searches. The maximum number of results to return Required/Optional Required Required Required Required

Output Values Name ResponseCode SearchCount CreatedDate FileType IsFile ItemName ItemPath SizeBytes Description A result code with the status of the search. If the result is 0 the method was successful. The number of results returned in the search. The date the file was added to the file system. The type of file. A flag to indicate whether the item is a file or folder. The name of the file or folder. The fully qualified path to the file or folder. The size of the file. 0 if the item is a folder. Sample Value 0 15 9/1/2007 Audio True Myimage.jpg MyFolder/MyImage.jpg 123456

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

Sharing Namespace
For Nirvanix Web Services 1.0 the sharing component only consists of hosting functionality. Host links are paths where everyone has read access. This could be used to host a website, share images, or other media, or to email links to files in a Nirvanix 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. back to top

Customer API
ListHostedItems
The ListHostedItems method is used to list all of the files and folders that the user has hosted. Input Parameters Parameter sessionToken pageNumber pageSize Output Values Name ResponseCode HostedItem Description A result code with the status of the copy. If the result is 0 the method was successful. An object that describes the host items. Sample Value 0 Description A valid session token for the user. The page number to list. The size of the page to return. Required/Optional Required Required Required

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. Input Parameters Parameter sessionToken Description A valid session token for the user. Required/Optional Required

sharePath Output Values Name ResponseCode

The path to the file or folder to be hosted.

Required

Description A result code with the status of the copy. If the result is 0 the method was successful.

Sample Value 0

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. Input Parameters Parameter sessionToken sharePath Output Values Name ResponseCode Description A result code with the status of the copy. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the user. The path to the file or folder to be has its permissions restricted. Required/Optional Required Required

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

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

Resize

The Resize method is used to resize an existing image. A new image will be created as a result and put into your file system. Input Parameters Parameter sessionToken srcFilePath destFilePath width height callbackURL Description A valid session token for the user. The path to the image file. The path to the destination image file. Image format conversions occur automatically based on the suffix of this file. i.e. .bmp The width of the new image. May be set to -1 if you want the width to be calculated based on the aspect ratio of the original image. Both width and height cannot be set to -1. The height of the new image. May be set to -1 if you want the height to be calculated based on the aspect ratio of the original image. Both width and height cannot be set to -1. The URL to be invoked by NWS when the image resizing has been completed. Required/Optional Required Required Required Required Required Optional

Output Values Name ResponseCode Description A result code with the status of the image resize command. If the result is 0 the method was successful. Sample Value 0

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 Parameter sessionToken srcFilePath destFilePath rotate flip callbackURL Description A valid session token for the user. The path to the image file. The path to the destination image file. Image format conversions occur automatically based on the suffix of this file. i.e. .bmp The number of degrees to rotate the image. Valid values are: RotateNone, Rotate90, Rotate180, Rotate270 The type of flip manipulation of the image. Valid values are: FlipNone, FlipHorizontal, FlipVertical, FlipHorizontalVertical The URL to be invoked by NWS when the image rotation/flip has been completed. Required/Optional Required Required Required Required Required Optional

Output Values Name ResponseCode Description A result code with the status of the image rotate/flip command. If the result is 0 the method was successful. Sample Value 0

Sample REST Request /ws/Image/RotateFlip.ashx?sessionToken=22b16933-2cd5-40ab981e-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. back to top

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

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> Example: http://123.123.123.123/MyApp/MyAccount/My%20Folder/My%20File%201.txt?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f In the case when the user has granted access of a file to the public, the sessionToken parameter is omitted from the URL. Example: http://123.123.123.123/MyApp/MyAccount/MyWebsite/index.html 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. back to top

Transfer Namespace
This namespace of the Nirvanix Web Services provides a set of API methods that allow a user to upload files to our Internet Media File System (IMFS). An HTTP upload interface is also provided. back to top

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

Parameter uploadToken path fileData endOfFile

Description A valid upload access token for the user. A byte[] array of the actual data to be sent. The maximum size of this array is 2,147,483,647 bytes.

Required/Optional Required Required

The path of the file being uploaded. This MUST match between successive calls to AppendFile. Required

If this is the last part of the file to be uploaded this should be true, this will flag the file as finished and move it into the folder specified. Files being uploaded will not appear until this last part is Required specified and sent.

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 Parameter uploadToken path fileData Description A valid upload access token for the user. A byte[] array of the actual data to be sent. The maximum size of this array is 2,147,483,647 bytes. Required/Optional Required Required

The path of the file being uploaded. This MUST match between successive calls to AppendFile. Required

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. 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: Local path C:\Photos\myDog.jpg C:\Photos\Trips\Hawaii\DSC001.jpg Actual destination IMFS path MyOnlinePhotos/myDog.jpb MyOnlinePhotos/Trips/Hawaii/DSC001.jpg

C:\Photos\Trips\Hawaii\DSC002.jpg C:\Photos\Trips\Hawaii\DSC003.jpg

MyOnlinePhotos/Trips/Hawaii/DSC002.jpg MyOnlinePhotos/Trips/Hawaii/DSC003.jpg

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 Parameter uploadToken destFolderPath forwardingUrl 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. Example: 1. Browser renders a page generated by a Nirvanix customer. The page contains a form with a file input. The action for the form is: http://node1.nirvanix.com/upload.ashx?uploadToken=ASdsdasd11233&destFolderPath=Photos/Vacations/2007Hawaii/DSC231256. jpg&forwardingUrl=www%2Egoogle%2Ecom%2Fsearch%3Fhl%3Den%26safe%3Doff%26pwst%3D1%26sa%3DX%26oi%3Dspell %26resnum%3D0%26ct%3Dresult%26cd%3D1%26q%3Ddogs%2Bcats%26spell%3D1%0D%0A 2. Upon submitting the form, the data is sent to Nirvanix via HTTP Post. When the upload completes, the user is redirected to the forwarding URL: http://www.google.com/search?hl=en&safe=off&pwst=1&sa=X&oi=spell&resnum=0&ct=result&cd=1&q=dogs+cats &spell=1&NVX.returnCode=0&NVX.errorMessage= 3. Browser renders the google.com page and has a chance to process any returnCode. Description A valid upload access token for the user. The destination path of the files being uploaded. The actual Required/Optional Required. This must come before the multipart form data Required. This must come before the multipart form data.

A valid URL to forward the user to after the upload completes or Optional. See below. has an error.

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. 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, a MD5 hash of the updated file is required 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 Parameter uploadToken destFolderPath fileMD5 callbackURL Output Values HTTP Update either responds with the following XML, or it forward the user (see Forwarding URL section below.) Description A valid upload access token for the user. The destination path of the file being updated. The MD5 hash of the complete updated file. A valid Url to notify the user after the update completes or has an error. Required/Optional Required. This must come before the multipart form data containing file content. Required. This must come before the multipart form data containing file content. Required. This must come before the multipart form data containing file content. Required.

<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 user's files. This component exposes the commands that allow a Master Account to create child accounts, and set and read their limits. back to top

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 Parameter SessionToken Username Password FirstName LastName MiddleInitial PhoneNumber EmailAddress EmailFormat Address1 Address2 City State CountryID PostalCode 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> A primary contact phone number The Email address associated with the account. The format the email will be sent to the account. (html/text) Description A valid session token for the user. The account username. The account password. An account contact name Details Required Required Length limit: 320 Required Length limit: 100 Optional Length limit: 30 Optional Length limit: 30 Optional Length limit: 1 Optional Length limit: 50 Optional Length limit: 1000 Optional Optional Length limit: 200 Optional Length limit: 200 Optional Length limit: 200 Optional Length limit: 2 Optional Optional Length limit: 50

<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 Parameter SessionToken Username 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> Description A valid session token for the user. The account username. Details Required Required

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 Parameter SessionToken Username 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"> Description A valid session token for the user. The account username. Details Required Required

<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 Parameter SessionToken Username 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> Description A valid session token for the user. The child account to operate on. Details Required Required

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 Parameter SessionToken Username Description A valid session token for the user. The account username. The feature type. Valid types are: ● StorageAmount - The total bytes stored. ● DownloadBandwidthAmount - The total number of bytes that can be downloaded per pay period. ● FileSizeDownloadLimit - The maximum size in bytes of a file that can be downloaded. ● UploadBandwidthAmount - The total number of bytes that can be uploaded per pay period. The feature value. Set to -1 to remove the limit. Details Required Required

Type

Required

Value

Required

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 Parameter SessionToken Username 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> Description A valid session token for the user. The child account to operate on. Details Required Required

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

Input Parameters Parameter sessionToken Username FirstName LastName MiddleInitial PhoneNumber CompanyName EmailAddress EmailFormat Address1 Address2 Locality City State CountryID PostalCode 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 Code 65101 65003 65001 65004 65005 65006 Description InvalidContactException InvalidSlaError AccountCreateException InvalidAppKey InvalidAccountType DuplicateUserNameUnderAppKey Details Occurs when a required contact field is missing Occurs when a contact field is too long Occurs if an email address is not valid Occurs if the supplied SLA is invalid Occurs if a billing contact is not provided at MasterAccount creation Occurs if no payment information is provided at MasterAccount creation Occurs if an invalid AppKey is used Occurs if non-Parent Account attempts to create a child Occurs if UserName is not unique for an AppKey See Country Code List for Valid values. TEXT or HTML Primary Phone Number Description A valid session token for the user. Details Required Required Required Required Required Required Required Required Length limit: 1000 Required Required Length limit: 200 Required Length limit: 200 Required Required Length limit: 200 Required Length limit: 2 Required Required Length limit: 50

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 Parameter sessionToken username xmlNotes Output Values A Response Code is always returned. If an error occurred, an Error Message is returned. Description A valid session token for the user or parent account. The account username. Well formed XML document Details Required Required Required

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 Parameter sessionToken username 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> Description A valid session token for the user or parent account. The account username. Details Required Required

ListChildAccounts
The ListChildAccounts method will retrieve the list of child accounts associated with the specified master account. Input Parameters Parameter sessionToken pageNumber pageSize Output Values Name ResponseCode Description A result code with the status of the ListChildAccounts command. If the result is 0 the method was successful. Sample Value 0 Description A valid session token for the logged in master account. The page number to list. The number of child accounts to list for the specified page. Required/Optional Required Required Required

Sample REST Request /ws/Accounting/ListChildAccounts.ashx?sessionToken=22b16933-2cd5-40ab981e-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. back to top

Customer API
Transcode
The Transcode method is used to convert an audio file from one format to another. Input Parameters Parameter sessionToken srcFilePath destFilePath callbackURL Description A valid session token for the user. The audio file to be transcoded. The resulting transcoded file. The audio format of this file will be based on the suffix. i.e. a file named foo.mp3 will be in MP3 format. The URL to be invoked then the transcode operation has been completed. The available options are: ● numberOfFrames - Minimum: 1 ● bitRate - Minimum: 0.0 ● numberOfChannels - Minimum: 1 options
REST

Required/Optional Required Required Required Optional

Optional

Each option is passed as a separate parameter. Ex: &numberOfFrames=10000&biteRate=192
SOAP

A string array of ':' delimited parameters. Ex: "numberOfChannels:100". Output Values Name ResponseCode Description A result code with the status of the transcode command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual transcode operation was successful. Sample Value 0

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

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

Customer API
Transcode
The Transcode method is used to convert a video file from one format to another. Input Parameters Parameter sessionToken srcFilePath destFilePath callbackURL Description A valid session token for the user. The video file to be transcoded. The resulting transcoded file. The video format of this file will be based on the suffix. i.e. a file named foo. mov will be in MOV QuickTime format. The URL to be invoked then the transcode operation has been completed. The available options are: ● numberOfFrames - Minimum: 1 ● frameRate - Minimum: 0.0 ● width - Minimum: 1 (May be set to -1 if a valid height is specified to maintain the aspect ratio) ● height - Minimum: 1 (May be set to -1 if a valid width is specified to maintain the aspect ratio) ● aspectRatio - Minimum: 0.0 (usually width/height) ● audioFreq - Must be Integer, Minimum: 0 (The audio sample frequency when converting to FLV files should be explicitly set to 11025, 22050 or 44100) options
REST

Required/ Optional Required Required Required Optional

Optional

Each option is passed as a separate parameter. Ex: &numberOfFrames=10000&frameRate=24&width=640&height=480&aspectRatio=1.33&audioFreq=44100
SOAP

A string array of ':' delimited parameters. Ex: "numberOfFrames:10000". Output Values Name ResponseCode Description A result code with the status of the transcode command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual transcode operation was successful. Sample Value 0

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 Parameter sessionToken srcFilePath destFolderPath callbackURL Description A valid session token for the user. The video file to have frames extracted from it. The folder path where the extracted frame images will be placed in the file system. The URL to be invoked then the frame extraction operation has been completed. A list of ':' delimited optional parameters. The allowable parameters and their corresponding limits are numberOfFrames (Minimum: 1), frameRate (Minimum: 0.0), width (Minimum: 1), height (Minimum: 1), startTimeOffset (Minimum: 0.0), frameName, frameFormat, frameNumberDigits (Minimum: -1). Either 'width' or 'height' may be set to -1 to maintain the aspect ratio of the video file frames, 'frameRate' is in frames per second. 'startTimeOffset' is the number of seconds to skip in the video prior to starting the frame extraction, 'frameName' is the name to be used for the images. Defaults to the name of the video file, 'frameFormat' is either 'jpg' (default), 'bmp', 'png', 'frameNumberDigits' is the number of digits to append to the 'frameName' when naming the extracted frame files. NOTE: If width is specified, height must be specified as well and vice versa. Required/Optional Required Required Required Optional

options

Optional

Output Values Name ResponseCode Description A result code with the status of the video frame extraction command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual video frame extraction operation was successful. Sample Value 0

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

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) domains 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. 2. 3. 4. Pricing for Virtual URLs Nirvanix Nameservers An area to create new Virtual URLs 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 recreated. 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.

back to top

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

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 Parameter Exception BaseException Output Values Description A default exception thrown by the .Net Runtime Custom Nirvanix exception intentionally thrown when an error occurs Details

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 Error Code 100 101 160 50103 55001 55100 65001 65002 65003 65004 65005 65006 65007 Type MissingRequiredParameter InvalidParameter UnsupportedOperation ParameterOutOfAcceptedRange InvalidPayment CreditCardChargeFailed CreateAccountFailed CreateAccountContactFailed InvalidSlaError InvalidAppKey InvalidAccountType DuplicateUserNameUnderAppKey DuplicateAppName

65008 65009 65010 65011 65012 65016 65101 65102 65104 70001 70002 70003 70004 70005 70006 70007 70008 70009 70010 70101 70102 70103 70104 70106 70107 70108 70109 70110 70111 80001 80003 80004 80005 80006 80007 80015 80016 80018 80019 80020 80021 80022 80023 80101 80102 80103 90001 90002 100001

PageSizeExceedsLimit DeletedAccount InvalidStatus InvalidSecurityResponse InvalidUserNameOrPassword DuplicateMasterAccountUserName InvalidContactParameter AppNameNotFound UserNameNotFound FolderNotFound FileNotFound PathNotFound AlreadyExists InvalidPath DownloadPathNotFound MetadataDoesNotExist FolderAlreadyExists PathTooLong FileFolderNameTooLong NullOrEmptyPath InvalidPathCharacter InvalidAbsolutePath InvalidRelativePath FileIntegrityError InvalidMetadata RangeNotSatisfiable PathTooShort FileOffline InvalidImageDimensions LoginFailed AccessDenied InvalidMasterAccountID InvalidBillableAccountID SessionNotFound AccountExpired OutOfBytes OutOfBytesNonOwner InvalidIPAddress DownloadFileSizeLimitExceeded UploadBandwidthLimitExceeded StorageLimitExceeded LimitAlreadyExceeded InvalidAccessToken InvalidSessionToken ExpiredAccessToken InvalidDownloadToken Configuration SSLRequired Database

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 day-name = = = [ day-of-week "," ] date FWS time [CFWS] ([FWS] day-name) / obs-day-of-week "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun" day month year 4*DIGIT / obs-year (FWS month-name FWS) / obs-month "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec" ([FWS] 1*2DIGIT) / obs-day time-of-day FWS zone hour ":" minute [ ":" second ] 2DIGIT / obs-hour 2DIGIT / obs-minute 2DIGIT / obs-second (( "+" / "-" ) 4DIGIT) / obs-zone

date year month month-name

= = = =

day time time-of-day hour minute second 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. back to top

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. CountryID 1 7 8 9 10 11 12 13 14 15 16 26 27 28 29 30 31 32 33 34 35 Country Name United States United Arab Emirates Afghanistan Antigua and Barbuda Anguilla Albania Armenia Netherlands Antilles Angola Antarctica Andorra Argentina American Samoa Austria Australia Aruba land Islands Azerbaijan Bosnia and Herzegovina Barbados Bangladesh

36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94

Belgium Burkina Faso Bulgaria Bahrain Burundi Benin Bermuda Brunei Darussalam Bolivia Brazil Bahamas Bhutan Bouvet Island Botswana Belarus Belize Canada Cocos (Keeling) Islands Congo, the Democratic Republic of the Central African Republic Congo Switzerland Cte d'Ivoire Cook Islands Chile Cameroon China Colombia Costa Rica Cuba Cape Verde Christmas Island Cyprus Czech Republic Germany Djibouti Denmark Dominica Dominican Republic Algeria Ecuador Estonia Egypt Western Sahara Eritrea Spain Ethiopia Finland Fiji Falkland Islands (Malvinas) Micronesia, Federated States of Faroe Islands France Gabon United Kingdom Grenada Georgia French Guiana Guernsey

95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153

Ghana Gibraltar Greenland Gambia Guinea Guadeloupe Equatorial Guinea Greece South Georgia and the South Sandwich Islands Guatemala Guam Guinea-Bissau Guyana Hong Kong Heard Island and McDonald Islands Honduras Croatia Haiti Hungary Indonesia Ireland Israel Isle of Man India British Indian Ocean Territory Iraq Iran, Islamic Republic of Iceland Italy Jersey Jamaica Jordan Japan Kenya Kyrgyzstan Cambodia Kiribati Comoros Saint Kitts and Nevis Korea, Democratic People's Republic of Korea, Republic of Kuwait Cayman Islands Kazakhstan Lao People's Democratic Republic Lebanon Saint Lucia Liechtenstein Sri Lanka Liberia Lesotho Lithuania Luxembourg Latvia Libyan Arab Jamahiriya Morocco Monaco Moldova, Republic of Montenegro

154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212

Madagascar Marshall Islands Macedonia, the former Republic of Mali Myanmar Mongolia Macao Northern Mariana Islands Martinique Mauritania Montserrat Malta Mauritius Maldives Malawi Mexico Malaysia Mozambique Namibia New Caledonia Niger Norfolk Island Nigeria Nicaragua Netherlands Norway Nepal Nauru Niue New Zealand Oman Panama Peru French Polynesia Papua New Guinea Philippines Pakistan Poland Saint Pierre and Miquelon Pitcairn Puerto Rico Palestinian Territory , Occupied Portugal Palau Paraguay Qatar Runion Romania Serbia Russian Federation Rwanda Saudi Arabia Solomon Islands Seychelles Sudan Sweden Singapore Saint Helena Slovenia

213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 back to top

Svalbard and Jan Mayen Slovakia Sierra Leone San Marino Senegal Somalia Suriname Sao Tome and Principe El Salvador Syrian Arab Republic Swaziland Turks and Caicos Islands Chad French Southern Territories Togo Thailand Tajikistan Tokelau Timor-Leste Turkmenistan Tunisia Tonga Turkey Trinidad and Tobago Tuvalu Taiwan, Province of China Tanzania, United Republic of Ukraine Uganda United States Minor Outlying Islands Uruguay Uzbekistan Holy See Vatican City State Saint Vincent and the Grenadines Venezuela Virgin Islands, British Virgin Islands, U.S. Viet Nam Vanuatu Wallis and Futuna Samoa Yemen Mayotte South Africa Zambia Zimbabwe

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
Sample HTTP multipart/form-data -----------------------------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
Sample HTTP multipart/form-data -----------------------------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
Sample HTTP multipart/form-data -----------------------------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
Sample HTTP multipart/form-data -----------------------------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)
Sample HTTP multipart/form-data -----------------------------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
Sample HTTP multipart/form-data -----------------------------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
Sample HTTP multipart/form-data -----------------------------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. back to top