Nirvanix Web Services API Developer's Guide v1.0: Release 1.1.4.5

Nirvanix Web Services
API Developer's Guide v1.0

Release 1.1.4.5
1/17/2007
● Getting Started: An introduction
to key concepts
❍ What is an Internet Media File Getting Started: An introduction to key concepts
System? back to top
❍ When to use an IMFS?
What is an Internet Media File System?

● Web Services Overview
An Internet Media File System (IMFS) is an Internet storage service that allows applications to upload, store and organize files
Calling Nirvanix Web Services
and subsequently access them using a standard Web Services interface. An IMFS is distributed clustered file system, accessed over
❍
■ SOAP the Internet, and optimized for dealing with media files (audio, video, etc). The goal of an IMFS is to provide massive scalability to deal
■ REST 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
■ HTTP GET storage assets.
The Nirvanix Media Filesystem
An IMFS is:
❍
Overview
● A file system for the Internet
● Implemented as a cluster of nodes
● Understanding Nirvanix ● Accessed via Web Services
Namespaces ● Consumed on-demand, as a service
❍ Why are Namespaces important? ● Optimized for managing media (large files, streaming video/audio, processing images, etc)
● Completely secure and protected
❍ Authentication Namespace
back to top
❍ Account Management Namespace
❍ IMFS Namespace
❍ Metadata Namespace
When to use an IMFS?
❍ Sharing Namespace 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
❍ Image Namespace of building a storage file system from scratch or buying an expensive storage solution, developers can avoid the upfront cost and
❍ Transfer Namespace 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.
❍ Audio Namespace
❍ Video Namespace 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
● Setting up Nirvanix MFS cases where there is resource contention associated with IT budgeting and staffing. An IMFS model provides a pay-as-you-go pricing
❍ Master Accounts model that scales with usage.
■ Creating Master Accounts 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
❍ Child Accounts limited to a small group of solutions, like transactional processing systems, access to block storage, 3D rendering or any other intense I/
■ Creating Child Accounts 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.
■ Deleting Child Accounts
■ Managing Child Account back to top
Information
❍ Authentication
● Accessing Nirvanix MFS Web Services Overview

❍ Creating Directories or Folders Web Services can be defined as software designed to support interoperable Machine-to-Machine interaction over a network. Web
❍ Manipulating Files and Folders 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
❍ Uploading Files clients and servers that communicate using XML messages that follow the SOAP or REST standards. Common in both the field and
■ SOAP 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
■ HTTP Upload
for automated client-side code generation in the mainstream Java and .NET SOAP frameworks. Some industry organizations, such as
❍ Downloading Files the WS-I, mandate both SOAP and WSDL in their definition of a Web service.
■ Request URL The specifications that define Web Services are intentionally modular, and as a result there is no one document that contains them
❍ Nirvanix Extensibility 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:
■ Metadata
❍ Tags 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.
❍ Sharing
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.
● Authentication Namespace
UDDI: A directory service for publishing and discovering metadata about Web Services to enable applications to find Web Services either
Customer API
at design time or runtime. Directory services are not relevant or included in the current implementation of this API.
❍
■ Login
Most of these core specifications have come from W3C, including XML, SOAP, and WSDL; UDDI comes from OASIS.
■ LoginProxy
■ Logout back to top
■ ChangePassword
■ SetChildAccountPassword Calling Nirvanix Web Services
● Internet Media File System The SOAP and REST protocols are used for transmission of the data and methods in this document. The SOAP protocol allows for
(IMFS) Namespace 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
❍ Customer API are available via SSL through HTTPS.
■ Common Errors
■ CopyFiles SOAP
■ CopyFolders
To call our web service your client must be able to consume our WSDL file. Most programming and scripting languages have tools
■ CreateFolders that facilitate consuming a web service. Generally, when your developer toolkit inspects the WSDL file it will auto-generate
■ DeleteFiles programming code that interfaces with the Web Services. Nirvanix has individual WSDLs for each namespace.
■ DeleteFolders An example WSDL link for the Authentication namespace is here:

■ ListFolder http://services.nirvanix.com/ws/Authentication.asmx?WSDL
■ MoveFiles When using Visual Studio you can attach to a SOAP WSDL through the "Add Web Reference" interface. This will allow you to create a
■ MoveFolders local object that acts as the remote SOAP interface handling the calls and instantiation for you automatically.
■ RenameFile
■ RenameFolder REST
■ GetDownloadNodes API Method Request Format: API methods are encapsulated by web pages within the API web site. To call a method, make a
■ GetOptimalUrls POST or GET request to the web page corresponding to the method you want to execute.
■ GetStorageNodeExtended The URL format for requests is:
http://services.nirvanix.com/ws/{NameSpace}/MethodName.ashx?name=value&name2=value2
■ GetStorageNode
■ SearchFileSystem Here is an example URL:
http://services.nirvanix.com/ws/Authentication/Login.ashx?appKey=8da051b0-a60f-4c22-
■ Sideload 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
● Metadata Namespace 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
❍ Customer API the caller logged in with application name "GoodApp" and account name "admin" then the following paths are equivalent:
■ DeleteAllMetadata
Absolute: /GoodApp/admin/web/index.html
■ DeleteMetadata
Relative: web/index.html
■ GetMetadata
■ SetMetadata In the case where relative path is absent or null, the accounts root folder is the assumed path.
■ DeleteAllTags 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.
■ DeleteTags
API Method Response Format: When an API method is called, a response is returned to the caller in XML format. The content
■ GetTags
type of the response will be "text/xml". The default XML response for methods that do not return data to the caller is:
■ SetTags
■ SearchMetadata <Response>
■ SearchTags <ResponseCode>0</ResponseCode>
</Response>
● Sharing Namespace
A "code" value of zero (code="0") indicates that the method completed successfully. If the code is not zero, then an error occurred and
Customer API
the XML response will look like this:
❍
■ ListHostedItems
■ CreateHostedItem <Response>
<ResponseCode>80006</ResponseCode>
■ RemoveHostedItem
<ErrorMessage>Session not found for ip = 10.0.0.1, token = 2dc8542b-210d-
45df-85df-b48b277c13c5</ErrorMessage>
● Image Namespace </Response>
❍ Resize
❍ RotateFlip HTTP GET
See section 9.3of RFC 2616 for information about GET and partial GET.
● Download Component
❍ Customer API back to top
■ HTTP Get
The Nirvanix Media File System Overview

● Transfer Namespace
The Nirvanix MFS is a proprietary file system that scales to exabytes with a single global namespace. It has a rich set of web
❍ Customer API service methods in its interface that allows for advanced storage application development in record time, providing developers with a
■ AppendFile great time-to-market advantage versus any other service or building infrastructure from scratch.
■ UploadFile back to top
■ HTTP Upload
● Accounting Namespace
❍ Customer API Understanding Nirvanix Namespaces
■ CreateChildAccount
■ DeleteChildAccount Why are Namespaces important?
■ GetAccountUsage
A namespace is the logical context in which a group of one or more entities might exist. For describing our Web Services, we
■ GetAccountLimits use namespaces to group related calls or methods. A method defined in a namespace is associated with that namespace. The same
■ SetAccountLimits 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
■ GetAccountInfo and namespaces mainly provide a means of grouping logically related methods into corresponding namespaces, thereby making the
■ SetAccountInfo system more modular.
■ GetAccountNotes The namespaces below are groupings of methods for our Web Services and are not to be confused with a file system namespace, in
■ SetAccountNotes 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.
■ ListChildAccounts
back to top
● Audio Namespace
❍ Customer API Authentication Namespace
Transcode
http://services.nirvanix.com/ws/Authentication.asmx?WSDL
■
● Video Namespace back to top
❍ Customer API
■ Transcode Account Management Namespace
■ ExtractFrames http://services.nirvanix.com/ws/Accounting.asmx?WSDL
● Virtual URL Hosting back to top
❍ Glossary
❍ Managing Virtual URLs IMFS Namespace
❍ Propagation Times http://services.nirvanix.com/ws/IMFS.asmx?WSDL
❍ Mapped Zones
back to top
❍ Generating Transfer Paths for
Mapped Virtual URLs
❍ Using Web Services with Virtual Metadata Namespace
URLs
http://services.nirvanix.com/ws/Metadata.asmx?WSDL
❍ Miscellaneous
back to top
● Exception Framework
Customer API
❍
Sharing Namespace
http://services.nirvanix.com/ws/Sharing.asmx?WSDL
● Appendices
❍ Date Formats back to top
❍ 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 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 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 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
A result code with the status of the login. If the result is 0 the method
ResponseCode 0
was successful.
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>
<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
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
A result code with the status of the login. If the result is 0 the method
ResponseCode 0
was successful.
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

<Response>
<SessionToken>54592180-7060-4D4B-BC74-2566F4B2F943</SessionToken>
</Response>
Sample SOAP Request
Authentication auth = new Authentication();

string sessionToken = auth.LoginProxy(appKey, userName, password, consumerIP);
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
sessionToken The session token that represents the user to be logged out. Required
Output Values
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
<Response>
</Response>
Sample SOAP Request
Authentication nirvAuth = new Authentication();

nirvAuth.Logout(sessionToken);

Go to WSDL for Logout.
ChangePassword
The ChangePassword is used to change an accounts own password.
Input Parameters
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
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
<Response>
</Response>
Sample SOAP Request

nirvAuth.ChangePassword(appKey, userName, oldPassword, newPassword);

Go to WSDL for ChangePassword.
SetChildAccountPassword
The SetChildAccountPassword is used by a master account to set a child accounts password.
Input Parameters
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
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
<Response>
</Response>
Sample SOAP Request

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

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.
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.
Occurs when the session cannot be found. This may happen after the session has been ended
80006 Session not found
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.
Input Parameters
sessionToken A valid session token for the user. Required
The path to the file to be copied. More than one file can be specified using a multiple instance
srcFilePath Required
of this parameter.
The path to the folder where the items will be copied to. The name of the item is not included
destFolderPath Required
in the destination folder.
Output Values
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
<Response>
</Response>
Sample SOAP Request
Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();

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

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
The folders to be copied. More than one folder may be specified using multiple instances of
srcFolderPath Required
this parameter.
destFolderPath The path to the folder where the items will be copied to. Required
Output Values
Sample REST Request
/ws/IMFS/CopyFolders.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&
srcFolderPath=Folder/subfolder/FolderToCopy&destFolderPath=Folder/
<Response>
</Response>
Sample SOAP Request

nirvFS.CopyFolders(sessionToken, new string[]{"Folder/subfolder/
FolderToCopy"}, "Folder/subfolder/DestFolder");
Go to WSDL for CopyFolders
CreateFolders
The CreateFolder method is used to create a new folder at the specified location.
Input Parameters
The path to the folder to be created. More than one folder may be specified using multiple
folderPath Required
instances of this parameter.
Output Values
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
<Response>
</Response>
Sample SOAP Request

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

Go to WSDL for CreateFolders
DeleteFiles
The DeleteFiles method is used to remove one or more files.
Input Parameters
The path to the file to be deleted. One or more files may be specified using multiple instances
filePath Required
of this parameter.
Output Values
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
<Response>
</Response>
Sample SOAP Request

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

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
The path to the folder to be deleted. One or more folders may be specified using multiple
folderPath Required
Output Values
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
<Response>
</Response>
Sample SOAP Request

nirvFS.DeleteFolders(sessionToken, new string[] {"Folders/subfolder"});

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
The path to the folder to be listed. If not specified, the logged in accounts root folder will be
folderPath Optional
listed.
pageNumber The page number to list. Required
pageSize The size of the page to return. Required
The sorting criteria. Must be one of the following: Name, CreatedDate, SizeBytes, FileType.
sortCode 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
sortDescending Optional
order is desired.
showMetadata Flag to indicate whether metadata is returned. Optional
showTags Flag to indicate whether tags are returned. Optional.
Output Values
Name 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
ResponseCode
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
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

<Response>
<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>
<Metadata></Metadata>
<FileTags></FileTags>
</File>
<File>
<Name>100001-somefile.txt</Name>
<Path>DirTest/F8/100001-somefile.txt</Path>
<Metadata></MetaData>
<FileTags></FileTags>
</File>
</ListFolder>
</response>
Sample SOAP Request

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

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
The path to the file to be move. More than one file can be specified using multiple instances of
srcFilePath Required
this parameter.
The path to the folder where the items will be moved to. The name of the item is not included
destFolderPath Required
in the destination folder.
Output Values
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/

<Response>
</Response>
Sample SOAP Request

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

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
The folders to be moved. More than one folder may be specified using multiple instances of
srcFolderPath Required
this parameter.
destFolderPath The path to the folder where the items will be moved to. Required
Output Values
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/
<Response>
</Response>
Sample SOAP Request

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

Go to WSDL for MoveFolders.
RenameFile
The RenameFile method is used to rename a file from one name to another.
Input Parameters
filePath The path to the file to be renamed. Required
newFileName The name of the new file. Required
Output Values
Sample REST Request
/ws/IMFS/RenameFile.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&filePath=Folder/subfolder/samplefile.txt&newFileName=mynewfile.txt

<Response>
</Response>
Sample SOAP Request

nirvFS.RenameFile(sessionToken, "Folder/subfolder/samplefile.txt", "mynewfile.txt");

Go to WSDL for RenameFile.
RenameFolder
The RenameFolder method is used to rename a folder from one name to another.
Input Parameters
folderPath The path to the folder to be renamed. Required
newFolderName The name of the new folder. Required
Output Values
Sample REST Request
/ws/IMFS/RenameFolder.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&folderPath=Folder/subfolder/myfolder&newFolderName=mynewfolder
Sample SOAP Request

nirvFS.RenameFolder(sessionToken, "Folder/subfolder/myfolder", "mynewfolder");
<Response>
</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
The path to the file to download. More than one may be specified using multiple instances of
filePath Required
this parameter.
Output Values
Name 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
ResponseCode
if an error occurs.
DownloadNode The corresponding download nodes if the response code is 0.
REST XSD

<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
70002 File not found Occurs if any of the files does not exist.
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

<Response>
<DownloadNode>node1.nirvanix.com</DownloadNode>
<DownloadNode>node1.nirvanix.com</DownloadNode>
</Response>
Sample SOAP Request

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

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
The path to the file to download. More than one may be specified using multiple instances of
filePath Required
this parameter.
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
if an error occurs.
Download The corresponding download link information if the response code is 0.
REST XSD

<xs:complexType>
<xs:sequence>
<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
70005 Invalid path Occurs if any of the files do not exist or a if a folder was passed in.
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

<Response>
<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

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);

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
sizeBytes The size of the file to be uploaded in bytes. Required
The IP address for the machine that will make the upload. The default is the IP address of
consumerIP Optional
the machine making this call.
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
True if a file with the same name in the destination folder should be overwritten by a file
fileOverwrite uploaded using the upload token. If this value is false, name collisions will result in an Optional
upload error. The default is false.
The number of seconds the upload token has until the first byte of an upload is transferred.
firstByteExpiration Optional
The default value is for 10 minutes.
The number of seconds the upload token has until an upload is completed. The default
lastByteExpiration Optional
value is for 3 days.
Output Values
Name Description
ResponseCode
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.
REST XSD

<xs:complexType>
<xs:sequence>
<xs:element name="UploadHost" maxOccurs="unbounded " />
<xs:element name="UploadToken" maxOccurs="unbounded " />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Errors
Sample REST Request
/ws/IMFS/GetStorageNodeExtended.ashx?sessionToken=290cc579-bc33-4283-
8701-68f5028b5adf&
sizeBytes=450000&consumerIP=127.0.0.1&ipRestricted=true&destFolderPath=/&
fileOverwrite=true&firstByteExpiration=6000&lastByteExpiration=259200

<Response>
<GetStorageNode>
<UploadHost>devnode1.nirvanix.com</UploadHost>
<UploadToken>kMHib15S~c_5IY1CphI~7cFRwvOB~E5evmH0CaL~WccWTQ_Vbu0yJGctig</UploadToken>
</GetStorageNode>
</Response>
Sample SOAP Request

StorageNode storageNode = GetStorageNodeExtended(sessionToken, 450000,
"127.0.0.1", true, "/", true, 6000, 259200);

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
sizeBytes The size of the file to be uploaded in bytes. Required
Output Values
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

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

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

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
username The username of the account to be searched. Required
The search string to look for files and folders. The '*' character may be used at the end of
searchTerm Required
the string to support wild card searches.
The file type to search for. Valid types are 'Unassigned', 'Document', 'Executable', 'Audio',
fileType Optional
'Video', 'Image'. Passing 'null' means to allow any file type in the search results.
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
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

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

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

Go to WSDL for SearchFileSystem.
Sideload
The Sideload command allows a user to load remote content into their Nirvanix file system.
Input Parameters
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
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
<Response>
</Response>
Sample SOAP Request

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

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
path The path to the file to have all metadata removed. Required
Output Values
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");
<Response>
</Response>

Go to WSDL for DeleteAllMetadata.
DeleteMetadata
The DeleteMetadata method is used to remove specified metadata from a file.
Input Parameters
The types of metadata to be deleted. More than one type may be specified using multiple
metadata Required
Output Values
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
<Response>
</Response>
Sample SOAP Request

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

Go to WSDL for DeleteMetadata.
GetMetadata
The GetMetadata method is used to retrieve all metadata from a file.
Input Parameters
path The path to the file to have all metadata retrieved. Required
Output Values
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
<?xml version="1.0" encoding="UTF-8" ?>

<Response>
<Metadata>
<Type>BitRate</Type>
<Value>4444</Value>
</Metadata>
</Response>
Sample SOAP Request

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

Go to WSDL for GetMetadata.
SetMetadata
The SetMetadata method is used to set specified metadata for a file.
Input Parameters
path The path to the file to have the metadata set. Required
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
metadata Required
characters. The maximum length for the metadata value is 400 characters. The following
characters are not allowed to specified in metadata: * |
Output Values
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
<Response>
</Response>
Sample SOAP Request

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

Go to WSDL for SetMetadata.
DeleteAllTags
The DeleteAllTags method is used to remove all tags from a file.
Input Parameters
path The path to the file to have all tags removed. Required
Output Values
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
<Response>
</Response>
Sample SOAP Request

nirvMeta.DeleteAllTags(sessionToken, "Folders/subfolder/myfile.txt");

Go to WSDL for DeleteAllTags.
DeleteTags
The DeleteTags method is used to remove specified tags from a file.
Input Parameters
The tags to be deleted. More than one type may be specified using multiple instances of this
tag Required
parameter.
Output Values
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/DeleteTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt&tag=foo&tag=bar
<Response>
</Response>
Sample SOAP Request

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

Go to WSDL for DeleteTags.
GetTags
The GetTags method is used to retrieve all tags from a file.
Input Parameters
path The path to the file to have all tags retrieved. Required
Output Values
ResponseCode A result code with the status of the tag get. If the result is 0 the method was successful. 0
Sample REST Request
/ws/Metadata/GetTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d

<Response>
<Tag>foo</Tag>
<Tag>bar</Tag>
</Response
Sample SOAP Request

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

Go to WSDL for GetTags.
SetTags
The SetTags method is used to set specified tags for a file.
Input Parameters
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 Required
tag, you will get all occurrences of that tag. The following characters are not allowed to
specified in a tag: * |
Output Values
ResponseCode A result code with the status of the tag set. If the result is 0 the method was successful. 0
Sample REST Request
/ws/Metadata/SetTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&path=Folders/subfolder/myfile.txt&tag=foo&tag=bar
<Response>
</Response>
Sample SOAP Request

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

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
searchKey The metadata search key. Example: Duration. Required
The search string to look for files and folders. The '*' character may be used at the end of the
searchTerm Required
string to support wild card searches. Wildcards are not supported if the searchKey is MD5.
Output Values
CreatedDate The date the file was added to the file system. 9/1/2007
Sample REST Request
/ws/Metadata/SearchMetadata.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&
username=myuser&searchKey=Duration&searchTerm=3*&maxResults=1000

<Response>
<SearchResults>
<Item>
</Item>
</SearchResults>
</Response>
Sample SOAP Request

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

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
The search string to look for in the tags. The '*' character may be used at the end of the string
searchTerm Required
to support wild card searches.
Output Values
CreatedDate The date the file was added to the file system. 9/1/2007
Sample REST Request
/ws/Metadata/SearchTags.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d&
username=myuser&searchTerm=mytag*&maxResults=1000

<Response>
<SearchResults>
<Item>
</Item>
</SearchResults>
</Response>
Sample SOAP Request

SearchResults results = nirvMeta.SearchTags(sessionToken, "myuser", "mytag*", 1000);
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
pageSize The size of the page to return. Required
Output Values
HostedItem An object that describes the host items.
Sample REST Request
/ws/Sharing/ListHostedItems.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&pageNumber=1&pageSize=10

<Response>
<HostedItem>
<IsFile>false</IsFile>
<SharePath>MyFolder/MySubfolder</SharePath>
</HostedItem>
<HostedItem>
<SharePath>MyFolder/MySharedFile.txt</SharePath>
</HostedItem>
</Response>
Sample SOAP Request
Nirvanix.Sharing nirvSharing = new Nirvanix.Sharing();

nirvSharing.ListHostedItems(sessionToken, 1, 10);

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
sharePath The path to the file or folder to be hosted. Required
Output Values
Sample REST Request
/ws/Sharing/CreateHostedItem.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&sharePath=Folder/subfolder/samplefile.txt

<Response>
<DownloadLink>http://mylinktodownloadthisfile.com</DownloadLink>
</Response>
Sample SOAP Request

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

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
sharePath The path to the file or folder to be has its permissions restricted. Required
Output Values
Sample REST Request
/ws/Sharing/RemoveHostedItem.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&sharePath=Folder/subfolder/samplefile.txt
<Response>
</Response>
Sample SOAP Request

nirvSharing.RemoveHostedItem(sessionToken, "Folder/subfolder/samplefile.txt");

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
srcFilePath The path to the image file. Required
The path to the destination image file. Image format conversions occur automatically based on
destFilePath Required
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
width Required
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
height Required
the aspect ratio of the original image. Both width and height cannot be set to -1.
callbackURL The URL to be invoked by NWS when the image resizing has been completed. Optional
Output Values
A result code with the status of the image resize command. If the result is 0 the method was
ResponseCode 0
successful.
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
<Response>
</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");

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
srcFilePath The path to the image file. Required
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,
rotate Required
Rotate180, Rotate270
The type of flip manipulation of the image. Valid values are: FlipNone, FlipHorizontal,
flip Required
FlipVertical, FlipHorizontalVertical
callbackURL The URL to be invoked by NWS when the image rotation/flip has been completed. Optional
Output Values
A result code with the status of the image rotate/flip command. If the result is 0 the method was
ResponseCode 0
successful.
Sample REST Request
/ws/Image/RotateFlip.ashx?sessionToken=22b16933-2cd5-40ab-
981e-dc9b6cfba06d&srcFilePath=
Folder/subfolder/samplefile.jpg&destFilePath=MyNewImages/samplefileRotated.gif
&rotate=Rotate90&flip=FlipHorizontal&callbackURL=http://mywebsite.com/mypage.aspx

<Response>
</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");

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
uploadToken A valid upload access token for the user. Required
path The path of the file being uploaded. This MUST match between successive calls to AppendFile. Required
A byte[] array of the actual data to be sent. The maximum size of this array is 2,147,483,647
fileData Required
bytes.
If this is the last part of the file to be uploaded this should be true, this will flag the file as finished
endOfFile 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

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);

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
uploadToken A valid upload access token for the user. Required
path The path of the file being uploaded. This MUST match between successive calls to AppendFile. Required
A byte[] array of the actual data to be sent. The maximum size of this array is 2,147,483,647
fileData Required
bytes.
Output Values
None
Sample SOAP Request

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);

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 Actual destination IMFS path

C:\Photos\myDog.jpg MyOnlinePhotos/myDog.jpb
C:\Photos\Trips\Hawaii\DSC001.jpg MyOnlinePhotos/Trips/Hawaii/DSC001.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
Required. This must come before the multipart form
uploadToken A valid upload access token for the user.
data
destFolderPath The destination path of the files being uploaded. The actual
data.
A valid URL to forward the user to after the upload completes or
forwardingUrl Optional. See below.
has an error.
Output Values
HTTP Upload either responds with the following XML, or it forward the user (see Forwarding URL section below.)
<Response>
<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.
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
uploadToken A valid upload access token for the user.
data containing file content.
destFolderPath The destination path of the file being updated.
fileMD5 The MD5 hash of the complete updated file.
A valid Url to notify the user after the update completes or has
callbackURL Required.
an error.
Output Values
HTTP Update either responds with the following XML, or it forward the user (see Forwarding URL section below.)
<Response>
<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 Description Details
SessionToken A valid session token for the user. Required
Username The account username. Required Length limit: 320
Password The account password. Required Length limit: 100
FirstName An account contact name Optional Length limit: 30
LastName Optional Length limit: 30
MiddleInitial Optional Length limit: 1
PhoneNumber A primary contact phone number Optional Length limit: 50
EmailAddress The Email address associated with the account. Optional Length limit: 1000
EmailFormat The format the email will be sent to the account. (html/text) Optional
Address1 Optional Length limit: 200
Address2 Optional Length limit: 200
City Optional Length limit: 200
State Optional Length limit: 2
CountryID Optional
PostalCode Optional Length limit: 50
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:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
DeleteChildAccount
The DeleteChildAccount command deletes the child account with the provided username. The provided Session Token must be from
the parent account login and the Application Key provided must be from an application owned by that parent account. The username must
be under the Application Key associated with the session token. If the username exists under the Application Key, it will be deleted.
A Response Code will be returned. This command is exposed as a web service.
Note: Deleting an account that a Virtual URL is mapped to will delete the Virtual URL.
Input Parameters
Username The account username. Required
Output Values
A Response Code is always returned. If an error occurred, an Error Message is also returned.
REST XSD

<xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType>
</xs:simpleType>
</xs:element>
</xs:schema>
GetAccountUsage
The GetAccountUsage command returns all of the usage metrics for the provided username under the provided Application Key.
A Response Code will be returned, as well as a list of usage. This command is exposed as a web service.
Input Parameters
Output Values
A Response Code is always returned. A successful execution will return the feature name and usage amount. If an error occurred, an
Error Message is returned.
REST XSD

<xs:complexType>
<xs:sequence>
<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:simpleType>
</xs:simpleType>
</xs:element>
<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
Username The child account to operate on. Required
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

<xs:element name="response">
<xs:complexType>
<xs:sequence>
<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:simpleType>
</xs:simpleType>
</xs:element>
<xs:element ref="ErrorMessage " minOccurs="0"/>
<xs:element ref="Type" minOccurs="0"/>
<xs:element ref="Value" minOccurs="0"/>
<xs:element ref="IsAppKeyLimit" minOccurs="0"/>
</xs:schema>
SetAccountLimits
The SetAccountLimits command sets the limits for the provided username under the provided Application Key. The Session Token
must belong to a Parent Account for the username. A Response Code will be returned. This command is exposed as a web service.
Input Parameters
The feature type. Valid types are:
● StorageAmount - The total bytes stored.
Type ● DownloadBandwidthAmount - The total number of bytes that can be downloaded per pay period. Required
● 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.
Value The feature value. Set to -1 to remove the limit. Required
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD

<xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType>
</xs:simpleType>
</xs:element>
</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
Username The child account to operate on. Required
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

<xs:complexType>
<xs:sequence>
<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="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:simpleType>
</xs:element>
<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="City" minOccurs="0"/>
<xs:element ref="State" minOccurs="0"/>
<xs:element ref="CountryID" minOccurs="0"/>
<xs:element ref="PostalCode" minOccurs="0"/>
</xs:schema>
SetAccountInfo
The SetAccountInfo command changes the account details for the provided session token.
Input Parameters
Username Required
FirstName Required
LastName Required
MiddleInitial Required
PhoneNumber Primary Phone Number Required
CompanyName Required
EmailAddress Required Length limit: 1000
EmailFormat TEXT or HTML Required
Address1 Required Length limit: 200
Address2 Required Length limit: 200
Locality Required
City Required Length limit: 200
State Required Length limit: 2
CountryID See Country Code List for Valid values. Required
PostalCode Required Length limit: 50
Output Values
REST XSD

<xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType>
</xs:simpleType>
</xs:element>
</xs:schema>
Errors
Occurs when a required contact field is missing Occurs when a contact field is too long
65101 InvalidContactException
Occurs if an email address is not valid
65003 InvalidSlaError Occurs if the supplied SLA is invalid
Occurs if a billing contact is not provided at MasterAccount creation Occurs if no payment
65001 AccountCreateException
information is provided at MasterAccount creation
65004 InvalidAppKey Occurs if an invalid AppKey is used
65005 InvalidAccountType Occurs if non-Parent Account attempts to create a child
65006 DuplicateUserNameUnderAppKey Occurs if UserName is not unique for an AppKey
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
sessionToken A valid session token for the user or parent account. Required
username The account username. Required
xmlNotes Well formed XML document Required
Output Values
REST XSD

<xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType>
</xs:simpleType>
</xs:element>
</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
sessionToken A valid session token for the user or parent account. Required
username The account username. Required
Output Values
REST XSD

<xs:complexType>
<xs:sequence>
<xs:element ref="xmlNotes" minOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType>
</xs:simpleType>
</xs:element>
<xs:element name="xmlNotes" type="xs:string"/>
</xs:schema>
ListChildAccounts
The ListChildAccounts method will retrieve the list of child accounts associated with the specified master account.
Input Parameters
sessionToken A valid session token for the logged in master account. Required
pageSize The number of child accounts to list for the specified page. Required
Output Values
A result code with the status of the ListChildAccounts command. If the result is 0 the method was
ResponseCode 0
successful.
Sample REST Request
/ws/Accounting/ListChildAccounts.ashx?sessionToken=22b16933-2cd5-40ab-
981e-dc9b6cfba06d
&pageNumber=1&pageSize=500
<Response>
<Account>childuser1</Account>
<Account>childuser2</Account>
</Response>
Sample SOAP Request
Nirvanix.Accounting nirvAcct = new Nirvanix.Accounting();

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

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
srcFilePath The audio file to be transcoded. Required
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.
callbackURL The URL to be invoked then the transcode operation has been completed. Optional
The available options are:
● numberOfFrames - Minimum: 1
● bitRate - Minimum: 0.0
● numberOfChannels - Minimum: 1
REST
options 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
A result code with the status of the transcode command. If the result is 0 the method was
ResponseCode successful. However, you must wait until your callback URL was invoked (if specified) in order to 0
determine if the actual transcode operation was successful.
Sample REST Request
/ws/Audio/Transcode.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFilePath=mysong.mp3&destFilePath=mynewsong.wav&numberOfFrames=10000&bitRate=192
<Response>
</Response>
Sample SOAP Request

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

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
Required/
Parameter Description
Optional
srcFilePath The video file to be transcoded. Required
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.
callbackURL The URL to be invoked then the transcode operation has been completed. Optional
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 Optional
REST
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
A result code with the status of the transcode command. If the result is 0 the method was
ResponseCode successful. However, you must wait until your callback URL was invoked (if specified) in order to 0
determine if the actual transcode operation was successful.
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
<Response>
</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);

Go to WSDL for Transcode
ExtractFrames
The ExtractFrames method will extract frames from a video file and store them as images.
Input Parameters
srcFilePath The video file to have frames extracted from it. Required
destFolderPath The folder path where the extracted frame images will be placed in the file system. Required
callbackURL The URL to be invoked then the frame extraction operation has been completed. Optional
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
options Optional
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.
Output Values
A result code with the status of the video frame extraction command. If the result is 0 the method
ResponseCode was successful. However, you must wait until your callback URL was invoked (if specified) in order 0
to determine if the actual video frame extraction operation was successful.
Sample REST Request
/ws/Video/ExtractFrames.ashx?sessionToken=22b16933-2cd5-40ab-981e-dc9b6cfba06d
&srcFilePath=myvideo.mpg&destFolderPath=myFrameFolder&numberOfFrames=10000&frameName=MyFrame
<Response>
</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);

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. Pricing for Virtual URLs
2. Nirvanix Nameservers
3. An area to create new Virtual URLs
4. A list of existing Virtual URLs that can be deleted, or have their mappings reassigned
This page provides all the tools needed to register and customize a Virtual URL with Nirvanix.
Propagation Times
New Virtual URLs require 24 - 72 hours for the DNS to propagate completely.
Mappings can be reassigned with only a 5 - 10 minute propagation delay.
Virtual URLs that are deleted will fail within 5 - 10 minutes. The URL will no longer resolve to the Nirvanix Nameservers after the 24 - 72
hour propagation time has elapsed.
Mapped Zones
All Virtual URLs have some sort of mapping. There are three types of mapping allowed:
1. Default Mapping - No specific mapping is designated. Use of this Virtual URL is limited to all Accounts of Applications which are
owned by the Master Account that registered the Virtual URL.
2. Application Mapping - The Virtual URL is mapped to a single Application of the Master Account that registered the Virtual URL.
Only children of the mapped Application can use this URL.
3. Account Mapping - The Virtual URL is mapped to a single Account of an Application of the Master Account that registered the
Virtual URL. Only the mapped Account can use the URL. This is helpful for sharing publicly hosted files.
*Note: Deleting an Application or Account that has Virtual URLs mapped to it will delete the Virtual URL. The Virtual URL can be re-
created. Normal setup charges would apply.
Generating Transfer Paths for Mapped Virtual URLs

The main benefit to mapping a Virtual URL is the ability to customize the access paths to get to individual files. Without mapping,
Nirvanix upload and download links take this form:
node1.nirvanix.com/<Application Name>/<Account Username>/Path to File
A default download link for a hosted file may look like this:
http://node1.nirvanix.com/App_Name/Account_Username/file_in_the_root_directory.txt
However, if Joe has the Virtual URL "storage.joe77.com" mapped to an Application, that Application name should not be included in the
URL. This might be a sample URL with Application Mapping:
http://node1.storage.joe77.com/Account_Username/File_in_the_root_directory.txt
Similarly, if Joe has the Virtual URL "storage.joe77.com" mapped to an Account, the Application Name and Account Username would not
be included. This link might look like this:
http://node1.storage.joe77.com/File_in_the_root_directory.txt
Here are the rules for creating Upload and Download paths:
1. Default Mapping - No part of the path is filled in.
2. Application Mapping - The name of the Application that the Virtual URL is mapped to is ALWAYS added to the beginning of the
path that is provided.
3. Account Mapping - The name of the Application and the username of the Account that the Virtual URL is mapped to is ALWAYS
added to the beginning of the path that is provided.
The GetOptimalUrls Web Service can be used to generate a complete download URL which takes advantage of any Virtual URL
mapping. Simply make the call to the GetOptimalUrls web method using the Virtual URL, and response back will be formatted correctly
with the same Virtual URL used.
*Note: When using a Virtual URL that has Application Mapping, the Application name must not be included in any upload or download
links. When using a Virtual URL mapped to an Account, the Application name and Account username must not be included in any upload
or download links. Doing either one of these will result in a "Path Not Found" exception.
Using Web Services with Virtual URLs

All web services actions are fully supported using Virtual URLs, using either the SOAP or REST protocol. There are no changes to the
Web Services Interface. Mappings are enforced at login, to provide a secure environment.
For example, Joe has the following
● The following Applications: App1 and App2
● The Virtual URL "storage.joe77.com" mapped to application App1
● An account of App1 with the username "Child1"
● An account of App2 with the username "Child of Unmapped App"
Joe can use the following URL to login "Child1"
http://services.storage.joe77.com/ws/Authentication/Login.ashx
However "Child of Unmapped App" cannot log in using the Virtual URL, because that Account does not belong to the Application that
is mapped to the Virtual URL. "Child if Unmapped App" can continue to use the following URL to perform all Web Services calls:
http://services.nirvanix.com/ws/Authentication/Login.ashx
These restrictions are enforced to prevent unauthorized accounts from spoofing Virtual URLs.
*Note: When providing paths for IMFS operations, the paths are used as provided, with no regards to Virtual URL Mapping. While
Mapped Applications and/or Account Usernames are pre-pended to Transfer links, they are NOT pre-pended to Web Services paths.
All paths used through web services are used as-is.
Miscellaneous
● A Virtual URL can only have one mapping. However, a single Application or Account can have several Virtual URLs mapped to it.
● All URLs with Records pointing to Nirvanix Nameservers must be registered through the Nirvanix Management Portal. This
restriction prevents URL spoofing.
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
Exception A default exception thrown by the .Net Runtime
BaseException Custom Nirvanix exception intentionally thrown when an error occurs
Output Values
A Response Code and Error Message is returned.
SOAP and REST XSD

<xs:element ref="ResponseCode" />
<xs:element ref="ErrorMessage" />
</xs:schema>
Sample REST Response

<response>
<ResponseCode>80101</ responseCode>
<ErrorMessage>Invalid Session Token</errorMessage>
</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 Type
100 MissingRequiredParameter
101 InvalidParameter
160 UnsupportedOperation
50103 ParameterOutOfAcceptedRange
55001 InvalidPayment
55100 CreditCardChargeFailed
65001 CreateAccountFailed
65002 CreateAccountContactFailed
65003 InvalidSlaError
65004 InvalidAppKey
65005 InvalidAccountType
65006 DuplicateUserNameUnderAppKey
65007 DuplicateAppName
65008 PageSizeExceedsLimit
65009 DeletedAccount
65010 InvalidStatus
65011 InvalidSecurityResponse
65012 InvalidUserNameOrPassword
65016 DuplicateMasterAccountUserName
65101 InvalidContactParameter
65102 AppNameNotFound
65104 UserNameNotFound
70001 FolderNotFound
70002 FileNotFound
70003 PathNotFound
70004 AlreadyExists
70005 InvalidPath
70006 DownloadPathNotFound
70007 MetadataDoesNotExist
70008 FolderAlreadyExists
70009 PathTooLong
70010 FileFolderNameTooLong
70101 NullOrEmptyPath
70102 InvalidPathCharacter
70103 InvalidAbsolutePath
70104 InvalidRelativePath
70106 FileIntegrityError
70107 InvalidMetadata
70108 RangeNotSatisfiable
70109 PathTooShort
70110 FileOffline
70111 InvalidImageDimensions
80001 LoginFailed
80003 AccessDenied
80004 InvalidMasterAccountID
80005 InvalidBillableAccountID
80006 SessionNotFound
80007 AccountExpired
80015 OutOfBytes
80016 OutOfBytesNonOwner
80018 InvalidIPAddress
80019 DownloadFileSizeLimitExceeded
80020 UploadBandwidthLimitExceeded
80021 StorageLimitExceeded
80022 LimitAlreadyExceeded
80023 InvalidAccessToken
80101 InvalidSessionToken
80102 ExpiredAccessToken
80103 InvalidDownloadToken
90001 Configuration
90002 SSLRequired
100001 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 "," ] date FWS time [CFWS]
day-of-week = ([FWS] day-name) / obs-day-of-week
day-name = "Mon" / "Tue" / "Wed" / "Thu" /

"Fri" / "Sat" / "Sun"
date = day month year
year = 4*DIGIT / obs-year
month = (FWS month-name FWS) / obs-month
month-name = "Jan" / "Feb" / "Mar" / "Apr" /

"May" / "Jun" / "Jul" / "Aug" /
"Sep" / "Oct" / "Nov" / "Dec"
day = ([FWS] 1*2DIGIT) / obs-day
time = time-of-day FWS zone
time-of-day = hour ":" minute [ ":" second ]
hour = 2DIGIT / obs-hour
minute = 2DIGIT / obs-minute
second = 2DIGIT / obs-second
zone = (( "+" / "-" ) 4DIGIT) / obs-zone
W3C Date and Time Format (See W3C Date and Time Format)
1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.
For HTTP applications, the date and time format is specified in RFC 2616 which is the format defined in RFC 1123 (which is an update
to RFC 822, changing the year format from YY to YYYY). This is currently supported under our Web services on both input and output.
A second format supported by our Web services is the WC3 Datetime Format which is a profile of a broader standard defined in ISO 8601.
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 Country Name

1 United States
7 United Arab Emirates
8 Afghanistan
9 Antigua and Barbuda
10 Anguilla
11 Albania
12 Armenia
13 Netherlands Antilles
14 Angola
15 Antarctica
16 Andorra
26 Argentina
27 American Samoa
28 Austria
29 Australia
30 Aruba
31 land Islands
32 Azerbaijan
33 Bosnia and Herzegovina
34 Barbados
35 Bangladesh
36 Belgium
37 Burkina Faso
38 Bulgaria
39 Bahrain
40 Burundi
41 Benin
42 Bermuda
43 Brunei Darussalam
44 Bolivia
45 Brazil
46 Bahamas
47 Bhutan
48 Bouvet Island
49 Botswana
50 Belarus
51 Belize
52 Canada
53 Cocos (Keeling) Islands
54 Congo, the Democratic Republic of the
55 Central African Republic
56 Congo
57 Switzerland
58 Cte d'Ivoire
59 Cook Islands
60 Chile
61 Cameroon
62 China
63 Colombia
64 Costa Rica
65 Cuba
66 Cape Verde
67 Christmas Island
68 Cyprus
69 Czech Republic
70 Germany
71 Djibouti
72 Denmark
73 Dominica
74 Dominican Republic
75 Algeria
76 Ecuador
77 Estonia
78 Egypt
79 Western Sahara
80 Eritrea
81 Spain
82 Ethiopia
83 Finland
84 Fiji
85 Falkland Islands (Malvinas)
86 Micronesia, Federated States of
87 Faroe Islands
88 France
89 Gabon
90 United Kingdom
91 Grenada
92 Georgia
93 French Guiana
94 Guernsey
95 Ghana
96 Gibraltar
97 Greenland
98 Gambia
99 Guinea
100 Guadeloupe
101 Equatorial Guinea
102 Greece
103 South Georgia and the South Sandwich Islands
104 Guatemala
105 Guam
106 Guinea-Bissau
107 Guyana
108 Hong Kong
109 Heard Island and McDonald Islands
110 Honduras
111 Croatia
112 Haiti
113 Hungary
114 Indonesia
115 Ireland
116 Israel
117 Isle of Man
118 India
119 British Indian Ocean Territory
120 Iraq
121 Iran, Islamic Republic of
122 Iceland
123 Italy
124 Jersey
125 Jamaica
126 Jordan
127 Japan
128 Kenya
129 Kyrgyzstan
130 Cambodia
131 Kiribati
132 Comoros
133 Saint Kitts and Nevis
134 Korea, Democratic People's Republic of
135 Korea, Republic of
136 Kuwait
137 Cayman Islands
138 Kazakhstan
139 Lao People's Democratic Republic
140 Lebanon
141 Saint Lucia
142 Liechtenstein
143 Sri Lanka
144 Liberia
145 Lesotho
146 Lithuania
147 Luxembourg
148 Latvia
149 Libyan Arab Jamahiriya
150 Morocco
151 Monaco
152 Moldova, Republic of
153 Montenegro
154 Madagascar
155 Marshall Islands
156 Macedonia, the former Republic of
157 Mali
158 Myanmar
159 Mongolia
160 Macao
161 Northern Mariana Islands
162 Martinique
163 Mauritania
164 Montserrat
165 Malta
166 Mauritius
167 Maldives
168 Malawi
169 Mexico
170 Malaysia
171 Mozambique
172 Namibia
173 New Caledonia
174 Niger
175 Norfolk Island
176 Nigeria
177 Nicaragua
178 Netherlands
179 Norway
180 Nepal
181 Nauru
182 Niue
183 New Zealand
184 Oman
185 Panama
186 Peru
187 French Polynesia
188 Papua New Guinea
189 Philippines
190 Pakistan
191 Poland
192 Saint Pierre and Miquelon
193 Pitcairn
194 Puerto Rico
195 Palestinian Territory , Occupied
196 Portugal
197 Palau
198 Paraguay
199 Qatar
200 Runion
201 Romania
202 Serbia
203 Russian Federation
204 Rwanda
205 Saudi Arabia
206 Solomon Islands
207 Seychelles
208 Sudan
209 Sweden
210 Singapore
211 Saint Helena
212 Slovenia
213 Svalbard and Jan Mayen
214 Slovakia
215 Sierra Leone
216 San Marino
217 Senegal
218 Somalia
219 Suriname
220 Sao Tome and Principe
221 El Salvador
222 Syrian Arab Republic
223 Swaziland
224 Turks and Caicos Islands
225 Chad
226 French Southern Territories
227 Togo
228 Thailand
229 Tajikistan
230 Tokelau
231 Timor-Leste
232 Turkmenistan
233 Tunisia
234 Tonga
235 Turkey
236 Trinidad and Tobago
237 Tuvalu
238 Taiwan, Province of China
239 Tanzania, United Republic of
240 Ukraine
241 Uganda
242 United States Minor Outlying Islands
244 Uruguay
245 Uzbekistan
246 Holy See Vatican City State
247 Saint Vincent and the Grenadines
248 Venezuela
249 Virgin Islands, British
250 Virgin Islands, U.S.
251 Viet Nam
252 Vanuatu
253 Wallis and Futuna
254 Samoa
255 Yemen
256 Mayotte
257 South Africa
258 Zambia
259 Zimbabwe
back to top
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
\r\n
-----------------------------170062046428149\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
-----------------------------170062046428149\r\n
Content-Disposition: form-data; name="updateContent1"; filename="myfile.dat"\r\n
\r\n
-----------------------------170062046428149--\r\n
Updated file content:
0x00 0xf1 0xf2 0xf3 0xf4 0xf5 0x06 0x07 0x08 0x09
Example 2: updating bytes 1 through 5 and byte 9

-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
/backup\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
0xf9\r\n
-----------------------------170062046428149--\r\n
0x00 0xf1 0xf2 0xf3 0xf4 0xf5 0x06 0x07 0x08 0xf9
Example 3: appending bytes 10 through 15

-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
/backup\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
0x0A 0x0B 0x0C 0x0D 0x0E 0x0F\r\n
-----------------------------170062046428149--\r\n
0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0A 0x0B 0x0C 0x0D 0x0E 0x0F
Example 4: updating bytes 1 through 4, truncating bytes 5-9

-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
/backup\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
0xf1 0xf2 0xf3 0xf4\r\n
-----------------------------170062046428149--\r\n
0x00 0xf1 0xf2 0xf3 0xf4
Example 5: updating entire file (Content-Range is optional in this case)

-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
/backup\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149--\r\n
0xf0 0xf1 0xf2 0xf3 0xf4
Example 6: invalid request with unspecified gap

-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
/backup\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
0x0B 0x0C 0x0D 0x0E 0x0F\r\n
-----------------------------170062046428149--\r\n
Request is invalid because byte 10 is not specified.
Example 7: invalid request with overlapping byte ranges

-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
/backup\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
-----------------------------170062046428149\r\n
\r\n
0xF8 0xF9\r\n
-----------------------------170062046428149\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

Nirvanix Web Services API Developer's Guide v1.0: Release 1.1.4.5

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Nirvanix Web Services API Developer's Guide v1.0: Release 1.1.4.5

Uploaded by

Copyright:

Available Formats

Nirvanix Web Services

API Developer's Guide v1.0

What is an Internet Media File System?

● Accessing Nirvanix MFS Web Services Overview

■ DeleteFolders An example WSDL link for the Authentication namespace is here:

The Nirvanix Media File System Overview

● Video Namespace back to top

● Virtual URL Hosting back to top

Setting up Nirvanix MFS

Creating Master Accounts

Creating Child Accounts

Deleting Child Accounts

Managing Child Account Information

Accessing Nirvanix MFS

Creating Directories or Folders

Manipulating Files and Folders

using (FileStream fs = new FileStream(localPath, FileMode.Open, FileAccess.Read))

// Upload some data to the file

// This is the end of file, so set the endofFile flag to 'true'

Web Browser Uploads

Custom Http Uploading

Sample HTTP multipart/form-data Upload

Partial File Upload

Partial File Update

For publicly hosted file, the sessionToken can be omitted:

<Metadata FileName=\"Goodbye Girl.mp3\">

Sample REST Request

Sample REST XML Response

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

Sample SOAP Request

Authentication auth = new Authentication();

Sample SOAP Response

Sample REST Request

Sample REST XML Response

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

Sample SOAP Request

Authentication auth = new Authentication();

Sample REST Request

Sample REST XML Response

Sample SOAP Request

Authentication nirvAuth = new Authentication();

Sample SOAP Response

Sample REST Request

Sample REST XML Response

Sample SOAP Request

Authentication nirvAuth = new Authentication();

Sample SOAP Response

Sample REST Request

Sample REST XML Response

Sample SOAP Request

Authentication nirvAuth = new Authentication();

Sample SOAP Response

Internet Media File System (IMFS) Namespace

The following are the Web Service interfaces for IMFS.

Sample REST Request

Sample REST XML Response

Sample SOAP Request

Nirvanix.IMFS nirvFS = new Nirvanix.IMFS();

Sample SOAP Response

Sample REST Request

Sample REST XML Response

Sample SOAP Request