Nirvanix Web Services
API Developer's Guide v1.0

Release 2.0.5.4

5/13/2008

Getting Started: An introduction to key concepts

back to top

What is an Internet Media File System?

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

An IMFS is:

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

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

Calling Nirvanix Web Services

The SOAP and REST protocols are used for transmission of the data and methods in this document. The SOAP protocol allows for simple integration with most languages and development systems. You can learn more about SOAP at http://en.wikipedia.org/wiki/SOAP. For more information about REST you can visit http://en.wikipedia.org/wiki/Representational_State_Transfer. REST and SOAP methods are available via SSL through HTTPS.

SOAP

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

An example WSDL link for the Authentication namespace is here:

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

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

REST

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

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

Here is an example URL:
http://services.nirvanix.com/ws/Authentication/Login.ashx?appKey=8da051b0-a60f-4c22-a8e0-d9380edafa6f&username=testuser&password=Abc123

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

Absolute: /GoodApp/admin/web/index.html
Relative: web/index.html

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

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

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

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

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

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

HTTP GET

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

back to top

The Nirvanix Media File System Overview

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

back to top

Understanding Nirvanix Namespaces

Why are Namespaces important?

A namespace is the logical context in which a group of one or more entities might exist. For describing our Web Services, we use namespaces to group related calls or methods. A method defined in a namespace is associated with that namespace. The same method could be independently defined in multiple namespaces, that is, the meaning associated with a method defined in one namespace is independent of the same method declared in any other namespace. However, in this version of the API method calls are unique and namespaces mainly provide a means of grouping logically related methods into corresponding namespaces, thereby making the system more modular.

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

back to top

Authentication Namespace

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

back to top

Account Management Namespace

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

back to top

IMFS Namespace

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

back to top

Metadata Namespace

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

back to top

Sharing Namespace

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

back to top

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.

Master Account Diagram
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 end-user accounts underneath an application within a master account. To create a child account, a username and password must be provided. Usernames must be unique within each application. Since our customers control the creation of child accounts for each application, they can decide to give their end-users access to multiple applications by providing the same username and password for every end-user. Similarly, they can have an implementation where each application is separate from the others.

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

Deleting Child Accounts

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

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

Managing Child Account Information

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

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

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

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

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

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

Web Browser Uploads

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

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

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

<html>
<body>
    <form ENCTYPE="multipart/form-data" action="http://nodex.nirvanix.com/Upload.ashx" method="post">
        Upload Token: <input type="text" name="uploadToken" /><br />
        Upload Folder: <input type="text" name="destFolderPath" /><br />
        File 1: <input type="file" name="uploadFile1"/><br />
        File 2: <input type="file" name="uploadFile2"/><br />
        <input type="submit" value="Upload"/>
    </form>
</body>
</html>
  

Custom Http Uploading

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

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="callbackURL"\r\n
\r\n
http://myserver.com/Callback.aspx?NVX.returnCode=0&NVX.absolutePath=//MyApp/Myaccount/myfolder/myfile.jpg&NVX.sizeBytes=1024\r\n
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="fileContent"; filename="myfile.dat"\r\n
Content-Type: binary/octet-stream\r\n
Content-Range: 0-4/5\r\n
\r\n
0xf0 0xf1 0xf2 0xf3 0xf4\r\n
-----------------------------170062046428149--\r\n
  

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

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

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

Content-Range

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

Partial File Upload

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

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

Partial File Update

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

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

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

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 downloads 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 Description Required/Optional
appKey The application key that contains the user to be logged in. Required
userName The account name to log in with. Required
password The password for the account. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the login. If the result is 0 the method was successful. 0
SessionToken A token that represents the logged in user. 54592180-7060-4D4B-BC74-2566F4B2F943

Sample REST Request

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

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <SessionToken>54592180-7060-4D4B-BC74-2566F4B2F943</SessionToken>
</Response>

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for Login.

LoginProxy

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

Input Parameters

Parameter Description Required/Optional
appKey The application key that contains the user to be logged in. Required
userName The account name to log in with. Required
password The password for the account. Required
consumerIP The consumer's IP address. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the login. If the result is 0 the method was successful. 0
SessionToken A token that represents the logged in user. 54592180-7060-4D4B-BC74-2566F4B2F943

Sample REST Request

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

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <SessionToken>54592180-7060-4D4B-BC74-2566F4B2F943</SessionToken>
</Response>

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for LoginProxy.

Logout

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

Input Parameters

Parameter Description Required/Optional
sessionToken The session token that represents the user to be logged out. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the rename. If the result is 0 the method was successful. 0

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 Description Required/Optional
appKey The application key that contains the user to change. Required
userName The account name to change. Required
oldPassword The old password for the account. Required
newPassword The new password to change to. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the password change. If the result is 0 the method was successful. 0

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 Description Required/Optional
appKey The application key that contains the user to change. Required
userName The master account name. Required
password The password for the master account. Required
childAccountUsername The child account name to set the password. Required
childAccountPass The child account password to set to. Required

Output Values

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

Sample REST Request

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

Sample REST XML Response

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

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for SetChildAccountPassword.

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 Description Details
100 Missing required parameters Occurs when one or more required parameters is missing.
70005 Invalid path Occurs when a folder or file path doesn't exist.
70009 Path too long Occurs when the total length of a relative path exceeds the maximum length of 512 characters.
70010 File/Folder name too long Occurs when a file or folder name exceeds the maximum length of 256 characters.
70102 Invalid path character Occurs when any path contains illegal characters.
80006 Session not found 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.
80101 Invalid session token 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.

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
srcFilePath The path to the file to be copied. More than one file can be specified using a multiple instance of this parameter. Required
destFolderPath 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

Output Values

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

Sample REST Request

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

Sample REST XML Response

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

Sample SOAP Request

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

Sample SOAP Response

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

CopyFolders

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

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
srcFolderPath The folders to be copied. More than one folder may be specified using multiple instances of this parameter. Required
destFolderPath The path to the folder where the items will be copied to. Required

Output Values

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

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

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the folder create. If the result is 0 the method was successful. 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 Description Required/Optional
sessionToken A valid session token for the user. Required
filePath The path to the file to be deleted. One or more files may be specified using multiple instances of this parameter. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the file delete. If the result is 0 the method was successful. 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 Description Required/Optional
sessionToken A valid session token for the user. Required
folderPath The path to the folder to be deleted. One or more folders may be specified using multiple instances of this parameter. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the folder delete. If the result is 0 the method was successful. 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.

GetPathInfo

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
itemPath The path to the file or folder. Required
showMetadata A flag to determine whether or not metadata is returned. Optional
showTags A flag to determine whether or not tags are returned. Optional
showIsShared A flag to determine whether or not the information related to the item being shared is returned. Optional

Output Values

Name Description
ResponseCode A result code with the status of the GetPathInfo request. The code will be 0 if the method is successful or one of the error codes below if an error occurs.
GetPathInfo The requested path information if the response code is 0.
ErrorMessage The error message if the response code is not 0.

Errors

Code Description Details
70005 Invalid path Occurs if the file or folder does not exist.

Sample REST Request

/ws/IMFS/GetPathInfo.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&itemPath=DirTest/F8.jpg&showMetadata=true&showTags=false&showIsShared=true

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <GetPathInfo>
      <ItemName>F8.jpg</ItemName>
      <IsFile>true</IsFile>
      <CreatedDate>Wed, 02 May 2007 13:36:41 GMT</CreatedDate>
      <SizeBytes>1000000</SizeBytes>
      <FileType>Image</FileType>
      <Metadata>
      	<MetaData FileName="F8.jpg">
              <Data Key="Height">480</Data>
	      <Data Key="MD5">JCiPH3sH4S3f/Ad93uWk+w==</Data>
              <Data Key="Width">640</Data>
        </MetaData>
      </Metadata>
      <Tags></Tags>
      <IsShared>false</IsShared>
      <ModifiedDate>Wed, 02 May 2007 13:36:41 GMT</ModifiedDate>
      <ItemID>1045632</ItemID>
   </GetPathInfo>
</response>

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for GetPathInfo.

ListFolder

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
folderPath The path to the folder to be listed. If not specified, the logged in accounts root folder will be listed. Required
pageNumber The page number to list. Required
pageSize The size of the page to return. Required
sortCode 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 be grouped together and all files will be grouped together. Optional
sortDescending Flag to indicate whether the sorting should be in descending order. Set to true if descending order is desired. Optional

Output Values

Name Description
ResponseCode A result code with the status of the ListFolder request. The code will be 0 if the method is successful or one of the error codes below if an error occurs.
ListFolder The requested page of folder content if the response code is 0.
ErrorMessage The error message if the response code is not 0.

Errors

Code Description Details
70001 Folder not found Occurs if the folder does not exist.

Sample REST Request

/ws/IMFS/ListFolder.ashx?sessionToken=8da051b0-a60f-4c22-a8e0-d9380edafa6f
&folderPath=DirTest/F8&pageNumber=1&pageSize=5&sortCode=Name&sortDescending=false

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <ListFolder>
      <TotalFolderCount>3</TotalFolderCount>
      <TotalFileCount>312509</TotalFileCount>
      <PageFolderCount>3</PageFolderCount>
      <PageFileCount>2</PageFileCount>
      <Folder>
         <FolderCount>0</FolderCount>
         <FileCount>1</FileCount>
         <Name>F8AChild</Name>
         <Path>DirTest/F8/F8AChild</Path>
         <CreatedDate>Wed, 02 May 2007 13:36:41 GMT</CreatedDate>
           <Metadata>
                       <MetaData FileName="video.wmv">
                            <Data Key="BitRate">55555</Data>
                            <Data Key="Duration">59</Data>
                            <Data Key="FrameRate">4444</Data>
                            <Data Key="Height">480</Data>
                            <Data Key="Width">640</Data>
                     </MetaData>
                 </Metadata>
         <FileTags>these|are|my|tags</FileTags>
      </Folder>
      <File>
         <SizeBytes>1000000</SizeBytes>
         <Name>100000-somefile.txt</Name>
         <Path>DirTest/F8/100000-somefile.txt</Path>
         <CreatedDate>Wed, 02 May 2007 15:14:14 GMT</CreatedDate>
         <Metadata></Metadata>
             <FileTags></FileTags>
      </File>
      <File>
         <SizeBytes>1000010</SizeBytes>
         <Name>100001-somefile.txt</Name>
         <Path>DirTest/F8/100001-somefile.txt</Path>
         <CreatedDate>Wed, 02 May 2007 15:14:14 GMT</CreatedDate>
         <Metadata></MetaData>
         <FileTags></FileTags>
      </File>
   </ListFolder>
</response>

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for ListFolder.

MoveFiles

The MoveFiles method is used to move a file from one location to another. The MoveFiles method can be used to move one or more files to a given folder.

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

Input Parameters

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

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the move. If the result is 0 the method was successful. 0

Sample REST Request

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

Sample REST XML Response

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

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for MoveFiles.

MoveFolders

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

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
srcFolderPath The folders to be moved. More than one folder may be specified using multiple instances of this parameter. Required
destFolderPath The path to the folder where the items will be moved to. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the move. If the result is 0 the method was successful. 0

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 Description Required/Optional
sessionToken A valid session token for the user. Required
filePath The path to the file to be renamed. Required
newFileName The name of the new file. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the rename. If the result is 0 the method was successful. 0

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 Description Required/Optional
sessionToken A valid session token for the user. Required
folderPath The path to the folder to be renamed. Required
newFolderName The name of the new folder. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the rename. If the result is 0 the method was successful. 0

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

Output Values

Name Description
ResponseCode 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.
DownloadNode The corresponding download nodes if the response code is 0.
ErrorMessage The error message if the response code is not 0.

REST XSD

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
           <xs:element name="ResponseCode" type="xs:integer" />
           <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
           <xs:element name="DownloadNode" maxOccurs="unbounded " type="xs:string" />
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Errors

Code Description Details
100 Missing required parameters Occurs when one or more required parameters is missing.
70002 File not found Occurs if any of the files does not exist.
70009 Path too long Occurs when the total length of a relative path exceeds the maximum length of 512 characters.
70010 File/Folder name too long Occurs when a file or folder name exceeds the maximum length of 256 characters.
70102 Invalid path character Occurs when any path contains illegal characters.
80006 Session not found 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.
80101 Invalid session token 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 Description Required/Optional
sessionToken A valid session token for the user. Required
filePath The path to the file to download. More than one may be specified using multiple instances of this parameter. Required
expiration The links time to expiration in seconds. Required
consumerIP The IP address of the web client which the link is best suited for. Optional
ipRestricted Boolean determining whether the link is restricted to the consumerIP. Optional

Output Values

Name Description
ResponseCode 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.
Download The corresponding download link information if the response code is 0.
Download/FilePath The relative Nirvanix path to the file.
Download/DownloadHost The host where the file can be downloaded. This normally corresponds to a node server name.
Download/DownloadToken The token that can be used to download the file. This token is set to expire after the provided expiration time.
Download/DownloadURL The full URL including download token and the node server. This is a direct link to download the file requested.
ErrorMessage The error message if the response code is not 0.

REST XSD

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="Response">
      <xs:complexType>
         <xs:sequence>
           <xs:element name="ResponseCode" type="xs:integer" />
           <xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
           <xs:element name="Download" maxOccurs="unbounded " />
              <xs:complexType>
                 <xs:sequence>
                    <xs:element name="FilePath" type="xs:string" />
                    <xs:element name="DownloadHost" type="xs:string" />
                    <xs:element name="DownloadToken" type="xs:string" />
                    <xs:element name="DownloadURL" type="xs:string" />
                 </xs:sequence>
              </xs:complexType>
           </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Errors

Code Description Details
100 Missing required parameters Occurs when one or more required parameters is missing.
70005 Invalid path Occurs if any of the files do not exist or a if a folder was passed in.
70009 Path too long Occurs when the total length of a relative path exceeds the maximum length of 512 characters.
70010 File/Folder name too long Occurs when a file or folder name exceeds the maximum length of 256 characters.
70102 Invalid path character Occurs when any path contains illegal characters.
80006 Session not found 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.
80101 Invalid session token 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 Description Required/Optional
sessionToken A valid session token for the user. Required
sizeBytes The size of the file to be uploaded in bytes. Required
consumerIP The IP address for the machine that will make the upload. The default is the IP address of the machine making this call. Optional
ipRestricted True if the upload token should be restricted to the consumerIP. The default is true. Optional
destFolderPath The folder path that any uploads using the provided upload token must be uploaded into. Required
fileOverwrite 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. Optional
firstByteExpiration The number of seconds the upload token has until the first byte of an upload is transferred. The default value is for 10 minutes.
This value is not enforced using AppendFile in SOAP or UploadFile in SOAP.
Optional
lastByteExpiration The number of seconds the upload token has until an upload is completed. The default value is for 3 days. Optional

Output Values

Name Description
ResponseCode 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.
UploadHost The server to upload to.
UploadToken An access token to pass into one of the upload methods when performing an upload.
ErrorMessage The error message if the response code is not 0.

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 Description Details
100 Missing required parameters Occurs when one or more required parameters is missing.
70009 Path too long Occurs when the total length of a relative path exceeds the maximum length of 512 characters.
70010 File/Folder name too long Occurs when a file or folder name exceeds the maximum length of 256 characters.
70102 Invalid path character Occurs when any path contains illegal characters.
80006 Session not found 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.
80101 Invalid session token Occurs when the session token is malformed.

Sample REST Request

/ws/IMFS/GetStorageNodeExtended.ashx?sessionToken=290cc579-bc33-4283-8701-68f5028b5adf&
sizeBytes=450000&consumerIP=127.0.0.1&ipRestricted=true&destFolderPath=/&
fileOverwrite=true&firstByteExpiration=6000&lastByteExpiration=259200

Sample REST XML Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
   <ResponseCode>0</ResponseCode>
   <GetStorageNode>
      <UploadHost>devnode1.nirvanix.com</UploadHost>
      <UploadToken>kMHib15S~c_5IY1CphI~7cFRwvOB~E5evmH0CaL~WccWTQ_Vbu0yJGctig</UploadToken>
   </GetStorageNode>
</Response>

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for GetStorageNodeExtended.

GetStorageNode

The GetStorageNode method is used to determine which storage node a file should be uploaded to. It returns the host to upload to and an Upload Token that will be used to authenticate.

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
sizeBytes The size of the file to be uploaded in bytes. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the rename. If the result is 0 the method was successful. 0
UploadHost The server to upload to. node1.nirvanix.com
AccessToken An access token to pass into one of the upload methods. ASDF123DASD

Sample REST Request

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

Sample REST XML Response

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

Sample SOAP Request

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

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 Description Required/Optional
sessionToken A valid session token for the user. Required
username The username of the account to be searched. Required
searchTerm 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. Required
fileType 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. Optional
minFileSize The minimum file size to search for. Should be set to 0 when searching for folders. Required
maxFileSize The maximum file size to search for. Should be set to 0 when searching for folders. Required
minCreatedDate The minimum created date for files. Required
maxCreatedDate The maximum created date for files. Required
maxResults The maximum number of results to return Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the search. If the result is 0 the method was successful. 0
SearchCount The number of results returned in the search. 15
CreatedDate The date the item was added to the file system. 9/1/2007
FileType The type of file. Audio
IsFile A flag to indicate whether the item is a file or folder. True
ItemName The name of the file or folder. Myimage.jpg
ItemPath The fully qualified path to the file or folder. MyFolder/MyImage.jpg
SizeBytes The size of the file. 0 if the item is a folder. 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 Description Required/Optional
sessionToken A valid session token for the user. Required
targetURL The URL to retrieve the remote content from. Required
destFilePath The Nirvanix file system path to store the remote content. Required
callbackURL The URL to be invoked by NWS when the sideload operation has been completed. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the sideload. If the result is 0 the method was successful. 0

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 or folder. Please note that the MD5 metadata type will NOT be removed with this call.

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
path The path to the file or folder to have all metadata removed. Required

Output Values

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

Sample REST Request

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

Sample SOAP Request

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

Sample REST XML Response

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

Sample SOAP Response

Go to WSDL for DeleteAllMetadata.

DeleteMetadata

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
path The path to the file or folder to have all metadata removed. Required
metadata The types of metadata to be deleted. More than one type may be specified using multiple instances of this parameter. Required

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the metadata delete. If the result is 0 the method was successful. 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 or folder.

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
path The path to the file or folder to have all metadata retrieved. Required

Output Values

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

Sample REST Request

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

Sample REST XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<Response>
   <ResponseCode>0</ResponseCode>
   <Metadata>
     <Type>BitRate</Type>
       <Value>4444</Value>
  </Metadata>
</Response>

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for GetMetadata.

SetMetadata

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
path The path to the file or folder to have the metadata set. Required
metadata 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

Output Values

Name Description Sample Value
ResponseCode A result code with the status of the metadata set. If the result is 0 the method was successful. 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 or folder.

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
path The path to the file or folder to have all tags removed. Required

Output Values

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

Sample REST Request

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

Sample REST XML Response

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

Sample SOAP Request

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

Sample SOAP Response

Go to WSDL for DeleteAllTags.

DeleteTags

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

Input Parameters

Parameter Description Required/Optional
sessionToken A valid session token for the user. Required
path The path to the file or folder to have the specified tags removed. Required