Nirvanix Web Services
API Developer's Guide
Document version 2.1
Product version 2.6.2
Related Documentation
See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for an in-depth explanation of more complex topics.
Getting Started: An introduction to key concepts
What is an Internet File System?
An Internet File System (IFS) is an Internet storage service that allows applications to upload, store, and organize files and subsequently access them using a standard Web Services interface. An IFS is a distributed clustered file system, accessed over the Internet, and optimized for dealing with large files (archive, video, research data, etc.) The goal of an IFS is to provide massive scalability to deal with the challenges of storage growth, with guaranteed access and availability regardless of time and location. Finally, an IFS gives applications the ability to access data securely, without the large fixed costs associated with acquiring and maintaining physical storage assets.
An IFS is:
- A file system for the Internet;
- Accessed via Web Services;
- Completely secure and protected;
- Implemented as a cluster of nodes;
- Consumed on-demand, as a service;
- Optimized for managing large files.
When to use the Nirvanix IFS?
Internet File Systems are great solutions for enterprises needing highly scalable, distributed, offsite storage for archiving, distributed content and collaboration, alternative options for near-line data retention, fixed content storage, and video/music/photo management. Instead of building a storage file system from scratch or buying an expensive storage solution, an enterprise can avoid the upfront cost and ongoing maintenance windows by simply connecting to an online storage service.
Software and service providers often want to focus their development and sustaining efforts on the core of their offering, and not have to learn or hire skills in Internet scale media storage, global network delivery, or user account management and security. These core competencies can be leveraged when storage services are provided by the IFS. Another benefit of using the IFS is in cases where there is resource contention associated with IT budgeting and staffing. The IFS model provides a pay-as-you-go pricing model that scales with usage.
At the same time, an IFS is not the best option for serving storage across the internet to I/O intensive applications inside of the data center. These applications require sub-millisecond response times that the Internet is not yet able to support. This characterization is limited to a small group of solutions, like transactional processing systems, access to block storage, 3D rendering or any other intense I/O application. The Nirvanix Storage Delivery Network (SDN) was built and optimized for managing large volumes of content, ease of integration, ease of scalability, and ease of control.
back to topUnderstanding Nirvanix Namespaces
A namespace is the logical context in which a group of one or more entities might exist. For describing our Web Services, we use namespaces to group related calls or methods. A method defined in a namespace is associated with that namespace by like functionality. The same method could be independently defined in multiple namespaces, that is, the meaning associated with a method defined in one namespace is independent of the same method declared in any other namespace. An example of this would be the Transcode call which is available in the Video and Audio namespaces.
Setting up Nirvanix IFS
There are two types of accounts the Nirvanix SDN, Master Accounts and Child Accounts. The Master account is responsible for payment associated with the use of our services and for management of end-user accounts. Master accounts are intended for our customers, who build and integrate their own applications to our services and generally should only need one master account for all their corporate needs. Master accounts can have multiple Applications in them. Applications are just that, specific multi-user applications that our customers can use to connect to our services. Within applications, child accounts are aggregated. Each child account has its own usage tracked separately, has its own contact info and can its usage can be limited individually.

Master Accounts
Master accounts can support multiple child accounts. For example, if you were using the Nirvanix IFS to launch a backup service, then you would create a single master account for the service, and then tie each new subscriber to your online backup service into a unique child account. The master account gives the developer an aggregated view into overall usage, while child accounts give developers the ability to segment storage and set strict limits on storage and bandwidth usage limits within these accounts. Master accounts can also have multiple applications (Storage Pools) for multiple services. When you create a new master account through our signup process, the first Application is created for you automatically.
Creating Master Accounts
Master accounts are created and managed via the Nirvanix Management Portal (NMP) through the signup page. This process will let you enter your billing, primary addresses and credit card information. Via the Nirvanix Management Portal, you can also create additional applications (Storage Pools) as desired. This enables developers to have multiple applications tied to and managed underneath a single master account.
back to topChild Accounts
Creating Child Accounts
Child accounts are created via a Web Services call. The CreateChildAccount command can be used to create individually managed end-user accounts underneath an application within a master account. To create a child account, a username and password must be provided. Usernames must be unique within each application. Since our customers control the creation of child accounts for each application, they can decide to give their end-users access to multiple applications by providing the same username and password for every end-user. Similarly, they can have an implementation where each application is separate from the others.
The SetAccountLimits command can be executed when a child account is successfully created. This command allows developers or applications to limit total space and bandwidth consumption for each child account. This feature provides ways to strictly enforce monthly usage limits for subscription or advertising-based services as well as allow offering multiple tiers of storage and bandwidth while pricing accordingly. At any time, you can view the current usage of an account with the GetAccountUsage command described below.
Deleting Child Accounts
The DeleteChildAccount command lets you remove a child account. The account is removed immediately and will not allow login or file system access. The current storage and usage information, such as total download bytes for this child account, will billed at the end of the month to the day you deleted the account. Deleted accounts will no longer be returned when listing child accounts in NMP.
Note: Deleting an account that a Virtual URL is mapped to will delete the Virtual URL.
Managing Child Account Information
SetAccountInfo is a method that allows you to set or change the existing information that is stored about an account.
GetAccountInfo is a method that allows you to extract the contact information for a single child account.
In addition to the contact information the method SetAccountNotes can be used to set per account configuration. This method only accepts valid XML data as parameter. Valid XML data must be formatted in standard XML Format as defined at W3C (http://www.w3.org/TR/2006/REC-xml11-20060816/).
The configuration XML can be used to store detailed account information specific to an account and was designed to be a light data repository for things like notes and other metadata on a child account that is only available to the master account.
back to topAuthentication
The authentication system takes in the application key and username/password to authenticate. It returns a session token that will be used for subsequent calls into the system. If you call the login method with a master account you must also provide an application key so it can be determined which application you wish to do file operations on. It is strongly suggested you use a secure socket for connecting your application with the Nirvanix IFS. This will reduce the chances an intermediary party will be able to determine your application key and password. The SessionToken returned will expire if not used within 20 minutes and will be associated with a specific IP address. This timeout is not configurable and is set to enforce a minimum level of security on sessions. Not limited to authentication, all connections are suggested to be done over a secure channel.
As an additional security control, accounts are automatically locked for 15 minutes after 5 failed login attempts. This holds true at both the master and child account levels. If needed, master accounts can be unlocked by customer support before the 15 minute window has elapsed.
back to topAccessing Nirvanix IFS
Creating Directories or Folders
To create a directory you can either upload a file to a path that does not yet exist or call the CreateFolders method passing the entire path you wish to create. If you send a path such as /Folder1/Folder2/Folder3/Folder4 and your current folder structure is:
Folder1 |_Folder2
Then after the call is executed the new structure will be:
Folder1
|_Folder2
|_Folder3
|_Folder4
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:
\ / |
In addition, all control characters forbidden by XML 1.0 are also disallowed:
U+0000 through U+001F with the exception of U+0009, U+000A, and U+000DPlease see http://www.w3.org/International/questions/qa-controls for more details regarding these forbidden control characters.
Note: slash "/" is reserved as the path delimiter. It cannot be part of a file name or folder name. Also when a file or folder name contains reserved URI characters such as "?" and "&", they must be encoded properly depending on your application's transport.
For more information about how to access files in a child or master account see the the protocols section
Nirvanix Extensibility
Metadata
Each file can have additional information stored as metadata. This metadata includes height and width for image files, and other secondary information about files that can be retrieved from the file contents. A sample mp3 is listed below to show the format of the metadata XML. Every file contains an base 64 encoded MD5 as part of the Metadata that is generated after the upload is performed. The MD5 metadata cannot be removed or modified.
<Metadata FileName=\"Goodbye Girl.mp3\"> <Data Key=\"MD5\">Ax53ddeDWw442iOkt==</Data> <Data Key=\"Album\">Anthology</Data> <Data Key=\"Artist\">Hunter Chordato</Data> <Data Key=\"BitRate\">256</Data> <Data Key=\"Duration\">263</Data> <Data Key=\"Genre\">Soundtrack</Data> <Data Key=\"IsVariableBitRate\">0</Data> <Data Key=\"Title\">Goodbye Girl</Data> <Data Key=\"Track\">5</Data> </Metadata>
Additional Key/Value pairs can be added or changed using SetMetadata and DeleteMetadata and DeleteAllMetadata.
back to topTags
Tags allow you to set a list of strings on a particular file or folder. They can be used in a fashion similar to tags in blog posts and are useful for search. The tags can be retrieved using GetTags and they can be set or deleted with SetTags, DeleteTags or DeleteAllTags.
back to topSharing
Sharing will set one or more folders to be available for viewing by non-authenticated users. This allows functionality such as video streaming and anonymous downloads by anyone who knows the path to the shared items. Any downloads by anonymous users of files that are shared will be applied to your usage and charged as such.
After you have a folder and files uploaded and in your account you can share them using CreateHostedItem. This web service will return the full download link to the file you are sharing or a partial download link if it is a folder. Below is an example of the input and output for the call to allow a shared item. This link will redirect you to the globally load-balanced file. Browsers should automatically support this. If you are writing a download application you will need to support the HTTP 302 Response, as defined in RFC 2616 section 10.3.3 302. When sharing a folder all sub-items (folders and files) are also shared.
Download URL: (Available publicly after success of the call)
http://services.nirvanix.com/AppName/ChildAccount/FolderShared/TestImage.jpg
If you wish to list the items you have previously shared you can call the method ListHostedItems, and then you can call the method RemoveHostedItem to remove any items you no longer wish to share.
back to topWeb Services Overview
Web Services can be defined as software designed to support interoperable Machine-to-Machine interaction over a network. Web Services are frequently Web APIs that can be accessed over the Internet and executed on a remote system hosting the requested services. The definition encompasses many different systems, but in common usage and throughout this document the term refers to clients and servers that communicate using XML messages that follow the SOAP or REST standards. Common in both the field and the terminology is the assumption that there is also a machine readable description of the operations supported by the server, often referred to as a Web Services Description Language (WSDL). The latter is not a requirement of SOAP endpoint, but it is a prerequisite for automated client-side code generation in the mainstream Java and .NET SOAP frameworks. Some industry organizations, such as the WS-I, mandate both SOAP and WSDL in their definition of a Web service.
The specifications that define Web Services are intentionally modular, and as a result there is no one document that contains them all. Additionally, there is neither a single, nor a stable set of specifications. There are a few "core" specifications that are supplemented by others as the circumstances and technologies dictate, including:
SOAP: An XML-based, extensible message envelope format, with "bindings" to underlying protocols. The primary protocols are HTTP and HTTPS, although bindings for others, including SMTP and XMPP, have been written.
WSDL: An XML document that allows service interfaces to be described, along with the details of their bindings to specific protocols. Typically used to generate server and client code, and for configuration. This API includes one WSDL document per namespace.
UDDI: A directory service for publishing and discovering metadata about Web Services to enable applications to find Web Services either at design time or runtime. Directory services are not relevant or included in the current implementation of this API.
Most of these core specifications have come from W3C, including XML, SOAP, and WSDL; UDDI comes from OASIS.
Calling Nirvanix Web Services (Protocols)
The SOAP and REST protocols are used for transmission of the data and methods in this document. The SOAP protocol allows for simple integration with most languages and development systems. You can learn more about SOAP at http://en.wikipedia.org/wiki/SOAP. For more information about REST you can visit http://en.wikipedia.org/wiki/Representational_State_Transfer. REST and SOAP methods are available via SSL through HTTPS. As a general practice the REST implementation is more flexible and should be preferred over SOAP when designing your system. See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for advantages and disadvantages.
REST
API Method Request Format: API methods are encapsulated by web pages within the API web site. To call a method, make a POST or GET request to the web page corresponding to the method you want to execute.
The URL format for requests is:
http://services.nirvanix.com/ws/{NameSpace}/MethodName.ashx?name=value&name2=value2
Here is an example URL:
http://services.nirvanix.com/ws/Authentication/Login.ashx?appKey=YOURAPPKEY&username=testuser&password=Abc123
API Method Paths: Many API methods require a "path" parameter. A path represents the folders and files within an account, similar to a windows path or URL path. In general, paths can be specified as either absolute or relative to the accounts root folder. For example, if the caller logged in with application name "GoodApp" and account name "admin" then the following paths are equivalent:
Absolute: //GoodApp/username/path/file.txt Relative: /path/file.txt
In the case where relative path is absent or null, the accounts root folder is the assumed path.
For most cases, relative paths should be used because it is simpler, easier, and shorter to reference. However, in cases where the caller needs to access another users file system (such as an master account managing a child account), absolute paths must be used.
The API calls that are plural indicate that one or more paths may be provided. Examples of this would be GetOptimalUrls which allows you to get several tokenized URLs in a single call. Singular API calls such as ListFolder operate on a single path at a time. For the most optimal operation the arrays should be passed in at most with 100 paths at a time.
API Method Response Format: When an API method is called, a response is returned to the caller in XML format. The content type of the response will be "text/xml". The default XML response for methods that do not return data to the caller is:
<Response> <ResponseCode>0</ResponseCode> </Response>
A "code" value of zero (code="0") indicates that the method completed successfully. If the code is not zero, then an error occurred and the XML response will look like this:
<Response> <ResponseCode>80006</ResponseCode> <ErrorMessage>Session not found for ip = 10.0.0.1, token = 2dc8542b-210d-45df-85df-b48b277c13c5 </ErrorMessage> </Response>
REST Output Format: All Nirvanix Web Services API responses can be optionally be output in JSON format. JSON (JavaScript Object Notation) is a lightweight data-interchange format. For JavaScript applications, it is a much more efficient format to parse than XML since it is a subset of the JavaScript Programming Language. By default, Nirvanix Web Services API responds in XML format. To enable JSON output format, simply append the query string "output=json" to the URL of any API call except Upload or Download. For example, this API call
/ws/IMFS/ListFolder.ashx?sessionToken=YOURSESSIONTOKEN&folderPath=DirTest/F8&pageNumber=1&pageSize=5&output=json
returns
{
"ResponseCode":0,
"ListFolder":{
"TotalFolderCount":3,
"TotalFileCount":365,
"PageFolderCount":3,
"PageFileCount":2,
"Folder":[
{
"FolderCount":0,
"FileCount":1,
"Name":"FolderA",
"Path":"DirTest\/F8\/FolderA",
"CreatedDate":"Wed, 02 May 2007 13:36:41 GMT",
"Metadata":null,
"FileTags":null
},
{
"FolderCount":1,
"FileCount":0,
"Name":"FolderB",
"Path":"DirTest\/F8\/FolderB",
"CreatedDate":"Wed, 02 May 2007 13:36:56 GMT",
"Metadata":null,
"FileTags":null
},
{
"FolderCount":1,
"FileCount":1,
"Name":"FolderC",
"Path":"DirTest\/F8\/FolderC",
"CreatedDate":"Wed, 02 May 2007 13:37:22 GMT",
"Metadata":null,
"FileTags":null
},
],
"File":[
{
"SizeBytes":1851,
"Name":"image.png",
"Path":"DirTest\/F8\/image.png",
"CreatedDate":"Fri, 11 Jul 2008 15:17:42 GMT",
"Metadata":
"<Metadata FileName=\"image.png\">
<Data Key=\"Width\">167<\/Data>
<Data Key=\"Height\">85<\/Data>
<Data Key=\"MD5\">GLGS2vG\/IhfLMnEHOCpuAw==<\/Data>
<\/Metadata>",
"FileTags":"these|are|my|tags"
},
{
"SizeBytes":637,
"Name":"text.txt",
"Path":"DirTest\/F8\/text.txt",
"CreatedDate":"Fri, 11 Jul 2008 15:18:29 GMT",
"Metadata":
"<Metadata FileName=\"text.txt\">
<Data Key=\"MD5\"> 5JiKJuJEqUv0Kmr8kadqYw== <\/Data>
<\/Metadata>",
"FileTags":null
}
]
}
}
JSON Callbacks: To allow embedding remote JSON in your web page the JSONcallback parameter is available. This will wrap the JSON result in a method name. When included as the source of a script call the JSON will be executed. By having the method that you pass in the JSON in your local page it will be called with the JSON object as the parameter. This avoids having to proxy the JSON result in a page hosted on your domain.
An example of this is:
/ws/Authentication/Login.ashx?appKey=XYZ-YOUR-APPKEY&username=YOURUSER&password=YOURPASSWORD&output=json&JSONcallback=loginresult
returns
loginresult({"ResponseCode":0,"SessionToken":"1cf8ff68-b93f-49a8-a375-5d437324b8fc"});
An example web page might look like:
<html>
<head>
<title>Display Session Token</title>
</head>
<script type="text/javascript">
function loginresult(json) {
alert("Session Token: " + json.SessionToken);
}
</script>
<script type="text/javascript" src="http://services.nirvanix.com/ws/Authentication/
Login.ashx?appKey=XYZ-YOUR-APPKEY&username=YOURUSER&password=YOURPASSWORD&output=json&
JSONcallback=loginresult"></script>
<body>
This will automatically call the loginresult method displaying the Session Token
in an alert.
</body>
</html>
SOAP
To call our web service your client must be able to consume our WSDL file. Most programming and scripting languages have tools that facilitate consuming a web service. Generally, when your developer toolkit inspects the WSDL file it will auto-generate programming code that interfaces with the Web Services. Nirvanix has individual WSDLs for each namespace.
An example WSDL link for the Authentication namespace is here:
http://services.nirvanix.com/ws/Authentication.asmx?WSDL
When using Visual Studio you can attach to a SOAP WSDL through the "Add Web Reference" interface. This will allow you to create a local object that acts as the remote SOAP interface handling the calls and instantiation for you automatically.
In the appendix you can find all of the SOAP WSDL links.
HTTP GET (File Retrieval)
The download component allows users of the Nirvanix Internet File System (IFS) to retrieve and download their files. For each download request, the download component performs authentication and authorization before actually serving out the bytes. At the end of each request, it also records the actual number of bytes served for accounting purposes including partial file downloads.
Because of the global caching node architecture, downloading a file from IFS is a two-step process. First the user must obtain the download location for each file path from the IFS interface. This will return the optimum download node which has the requested file based on the user's geographical location or SLA. Once this download node is known, the user can simply perform an HTTP get request to download the file from that node.
Once the download node for a file is known, the file can be downloaded by a normal HTTP Get request. The download URL has the following
format:
http://<DownloadNode>/<AppName>/<AccountName>/<RelativeFilePath>?sessionToken=<SessionToken>
Example:
http://123.123.123.123/MyApp/MyAccount/My%20Folder/My%20File%201.txt?sessionToken=YOURSESSIONTOKEN
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.
For additional information on the HTTP GET protocol, see section 9.3 of RFC 2616 for information about GET and partial GET (progressive download).
back to topDownloading Files
See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for further discussion about downloading files, including recommendations for retry and reroute logic.
Request URL
To download a file from the Nirvanix IFS, you can make a REST request to the transfer node using the GET method. The URL has the following format:
http://<Node>/<sessionToken>/<appName>/<userName>/<path>
For publicly hosted file, the sessionToken can be omitted:
http://<Node>/<appName>/<userName>/<path>
You can also access files using an access token created by the GetOptimalUrls call:
http://<Node>/<downloadtoken>/<appName>/<userName>/<path>
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://services.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt
Optionally, you can also specify the downloads content disposition with the query parameter "disposition". Valid values for this parameter are "inline" and "attachment". This modifies the returned Content-Disposition header and can allow browsers to be prompted to save the file or show the contents as part of the web page.
Example:
http://services.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt?disposition=inline
http://services.nirvanix.com/MyApp/MyUser1/folder1/folder2/hostedFile.txt?disposition=attachment
To obtain a session token, please see the Login method in the Authentication namespace.
To obtain the transfer node, please see the GetDownloadNodes method in the IFS namespace. As an alternative, and to make this a one-step process, you can also make the same download request to services.nirvanix.com and be redirected to the correct transfer node. This redirection uses a HTTP 302 response with the node specified in the location header.
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 IFS file download accepts the following standard HTTP request headers:
- If-Modified-Since
- If-None-Match
- Range
Response Headers
Nirvanix IFS file download response includes the following standard HTTP response headers:
- Content-Length
- Content-Type
- Content-Range (if requesting range)
- Content-Disposition (if specified in the request)
- Last-Modified
- ETag
Uploading Files
For optimal performance, the process to upload files is a 2-step process, where the Upload node is first identified by the method GetStorageNode or GetStorageNodeExtended, followed by the upload to that particular node. The upload token and upload servers IP address are retrieved by GetStorageNode. The Upload Token will expire (default is 10 minutes for first byte, 72 hours for last byte) and is not refreshed. This means the token will expire even if it is being used, unlike the session token. Before each upload you must ask for the upload node and use the information for that upload. Upload tokens should be used only once per file being uploaded so there is no chance of a collision while doing uploads.
See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for more discussion of upload, including recommendations for retry and reroute logic.
HTTP Upload
The HTTP protocol allows a multipart/form-data POST to upload files using "/Upload.ashx". Once the HTTP post is complete the response is a summary of the upload. Optionally the user can be forwarded to another URL after the upload is complete. If the user is forwarded, some additional parameters are appended to the forwarding URL. This allows users to upload directly from a webpage to the Nirvanix IFS. Another option is to specify a callback URL. This URL is invoked when the file has been completely uploaded.
The IFS destination of upload files is <destFolderPath>/<non-common request path-part>/<request file name>
For example if the user uploads the files in a single request using destFolderPath = "MyOnlinePhotos" the following are the resulting destination IFS paths:
| Local path | Actual destination IFS path |
|---|---|
| C:\Photos\myDog.jpg | MyOnlinePhotos/myDog.jpb |
| C:\Photos\Trips\Hawaii\DSC001.jpg | MyOnlinePhotos/Trips/Hawaii/DSC001.jpg |
| C:\Photos\Trips\Hawaii\DSC002.jpg | MyOnlinePhotos/Trips/Hawaii/DSC002.jpg |
| C:\Photos\Trips\Hawaii\DSC003.jpg | MyOnlinePhotos/Trips/Hawaii/DSC003.jpg |
When submitting a request with multiple files if one of those files has an error such as a path longer than 512 characters all files will be processed until the failed file. The response will be for the file that failed and no information will be returned for the success cases.
The maximum content size is limited to the maximum content-length in the http request which is: 2097150 kilobytes. If you exceed the maximum value you get a 10001 error.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| uploadToken | The valid upload access token for the user. May be in POST's URL or form's non-file part (before the form's fileContent part). | Required |
| destFolderPath | The destination path of the files being uploaded. May be in POST's URL or form's non-file part (before the form's fileContent part). | Required |
| forwardingURL | The valid URL to forward the user to after the upload completes or has an error. May be in POST's URL or form's non-file part (before the form's fileContent part). | Optional |
| callbackURL | The valid URL to invoke after the upload completes or has an error. May be in POST's URL or form's non-file part (before the form's fileContent part). | Optional |
| rangeOverwrite | See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx , Upload Retry Logic section. Values are "true" or "false", defaults to false. Do not attempt to use this for random access writing! May be in POST's URL or form's non-file part (before the form's fileContent part). | Optional |
| fileMD5 | The base 64 encoded MD5 hash of the uploaded file. Example: iIJ8xeS5SwyGYmjSNltwHQ==. May be in POST's URL or form file part ("Content-MD5"). After final POST of file data, the upload fails with error 70129 (MD5DoesNotMatch) if the MD5 of the uploaded file does not match this value. For multiple POSTs per file, fileMD5 must be specified in each POST. All but the final POST must supply a dummy value at least one character long; this allows a client to calculate the file MD5 on-the-fly as each chunk is uploaded. | Optional |
| metadata | The metadata to be associated with the uploaded file. May be in POST's URL or form file part ("Content-Metadata"). Metadata is specified as: type:value,type:value,... . Upload fails with error 70107 (InvalidMetadata) if metadata is not specified in the correct format. For multiple POSTs per file, the parameter need only be specified in the final POST. | Optional |
Output Values
HTTP Upload either responds with the following XML, or it forwards the response via a URL (see Forwarding URL section below).
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the move. If the result is 0 the method was successful. | 0 |
REST Response XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element ref="FilesUploaded" minOccurs="0"/>
<xs:element ref="BytesUploaded" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="FilesUploaded">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="BytesUploaded">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
http://node1.nirvanix.com/Upload.ashx?uploadToken=abcd12345&destFolderPath=mydata/myfile.bin
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> <FilesUploaded>1</FilesUploaded> <BytesUploaded>105450</BytesUploaded> </Response>
Errors
| Error Code | Type | Details |
|---|---|---|
| 100 | MissingRequiredParameter | Occurs when destFolderPath or uploadToken is missing. |
| 70004 | AlreadyExists | Occurs when destination file already exists. See GetStorageNodeExtended's fileOverwrite option. |
| 70121 | InvalidUploadRequest | Occurs when the request is bad such as: syntax error in form, form content length in form does not match data sent, request data too long, no content in form, etc. |
| 80003 | AccessDenied | Occurs when upload token does not grant access to the destination path. |
| 80021 | StorageLimitExceeded | Occurs when account or application has exceeded its allotted storage space. |
| 80023 | InvalidAccessToken | Occurs when upload token is invalid. |
| 80102 | ExpiredAccessToken | Occurs when upload token has expired. |
| 80104 | RestrictedIPAddress | Occurs when upload originates from an IP address that does not match restrictions set when GetStorageNodeExtended was called to obtain the upload token. |
Forwarding URL
If a forwardingURL is passed it must contain a valid query string. It can optionally include the forwarding protocol. When not included the protocol defaults to HTTP. Users are responsible for URL encoding this parameter. See http://www.blooberry.com/indexdot/html/topics/urlencoding.htm for reserved characters that are important for users to encode. For a sample of how to URL encode see http://www.w3schools.com/tags/ref_urlencode.asp.
The fowardingUrl is appended with the following parameters:
NVX.returnCode an integer representing the status of the upload. Did it fail? Success? Valid response codes: see standard return codes; return
code 0 means no error.
NVX.errorMessage a string describing the error message associated with any error being returned.
Any parameters provided in the request will also be included in the output. This can be useful for passing the filename and other information that the landing location may need to handle processing the upload.
Example:
- 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 - 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= - Browser renders the google.com page and has a chance to process any returnCode.
Callback URL
Users are responsible for URL encoding this parameter. See http://www.blooberry.com/indexdot/html/topics/urlencoding.htm for reserved characters that are important for users to encode. For a sample of how to URL encode see http://www.w3schools.com/tags/ref_urlencode.asp.
The callbackURL is appended with the following parameters:
NVX.returnCode an integer representing the status of the upload. Did it fail? Success? Valid response codes: see standard return codes; return
code 0 means no error.
NVX.errorMessage a string describing the error message associated with any error being returned.
NVX.absolutePath a string describing the absolute path of the file that was uploaded.
NVX.sizeBytes a long describing the size in bytes of the file that was uploaded.
Any parameters provided in the request will also be included in the output. This can be useful for passing the filename and other information that the landing location may need to handle processing the upload. This is often used to update external databases that keep track of paths within Nirvanix for websites.
Web Browser Uploads
When submitting a request with multiple files, if one of those files has an error such as a path longer than 512 characters all files will be processed in order until the failed file. The response will be for the file that failed and no information will be returned for the success cases. The rest of the request will be discarded.
This allows users to upload directly from a webpage to the Nirvanix IFS.
Below is a simple example of a HTML form that can upload through the HTTP protocol. The "nodex.nirvanix.com" and "UPLOADTOKEN" should be replaced with the values returned from the GetStorageNode API call.
A question that often comes up is the size of the download passed to the GetStorageNode and GetStorageNodeExtended when using a web client to upload. In these instances you will not know the size ahead of time and should instead use the best guess for the file size such as the average file size for you.
<html>
<body>
<form ENCTYPE="multipart/form-data" action="http://nodex.nirvanix.com/Upload.ashx" method="post">
<input type="hidden" name="uploadToken" value="UPLOADTOKEN" /><br />
Upload Folder: <input type="text" name="destFolderPath" /><br />
Metadata 1: <input type="text" name="metadata" /><br />
File 1: <input type="file" name="uploadFile1"/><br />
Metadata 2: <input type="text" name="metadata" /><br />
File 2: <input type="file" name="uploadFile2"/><br />
<input type="submit" value="Upload"/>
</form>
</body>
</html>
Custom Http Uploading
The http protocol allows a multipart/form-data POST (RFC 1867) to upload files using "/Upload.ashx". You can pass two required parameters "uploadToken" and "destFolderPath" in the form data. These must precede any multipart form data which contains file content. This allows us to verify security before attempting to accept the upload, if this is not done you will receive an error.
You may upload multiple files in one form if all the file data for each file fits in that form. When a file spans multiple forms (Partial File Upload) by incrementing the Content-Range value in each form sent, you must specify only one file per form.
The maximum content size is limited to the maximum content-length in the http request which is: 2,097,150 kilobytes. If you exceed the maximum value you get a 10001 error.
To handle the multipart/form-data post directly you can use libraries such as Curl or other direct writes to the HTTP headers. This allows you to do uploads outside of the browser and stream the data you wish to upload directly to the Nirvanix servers. A sample HTTP request's content is provided below as an example.
-----------------------------170062046428149\r\n Content-Disposition: form-data; name="uploadToken"\r\n \r\n fe-pC9v9~pRYkzGkBHQ~STJX0Ac2~48J3zyLxVO~APDbYlYSk5JO8xFTZw\r\n -----------------------------170062046428149\r\n Content-Disposition: form-data; name="destFolderPath"\r\n \r\n /backup\r\n -----------------------------170062046428149\r\n Content-Disposition: form-data; name="forwardingURL"\r\n \r\n http://myserver.com/uploadComplete.aspx?file=/backup/myfile.dat\r\n -----------------------------170062046428149\r\n Content-Disposition: form-data; name="callbackURL"\r\n \r\n http://myserver.com/Callback.aspx?NVX.returnCode=0&NVX.absolutePath= //MyApp/Myaccount/myfolder/myfile.jpg&NVX.sizeBytes=1024\r\n -----------------------------170062046428149\r\n Content-Disposition: form-data; name="fileContent"; filename="myfile.dat"\r\n Content-Type: binary/octet-stream\r\n Content-Range: 0-4/5\r\n Content-MD5: zie0mjZg+7Gf65HcHSJ/QQ==\r\n Content-Metadata: type1:value1,type2:value2 \r\n 0xf0 0xf1 0xf2 0xf3 0xf4\r\n -----------------------------170062046428149--\r\n
Each form data part is separated by a boundary. In the example above, this boundary appears as "-----------------------------170062046428149". This is a unique value that must not appear in the data. The \r\n throughout the form data represents carriage return/linefeed characters that is used as the separator for lines in a POST of the multipart/form-data. Each form data part begins with the header information for that part followed by the content of that part which may be the value of an input parameter of the form or the content of a file. A blank line delimits the header from the content. More information on HTTP Headers can be found in RFC 2616 Section 14.
The HTTP headers of parts containing file content includes the following:
- Content-Disposition - Defines the file name
- Content-Type - Defines the type of file being uploaded. Binary/octet-stream is generic binary data and can be used for all file types.
- Content-Range (Optional) - Lets you define portions of the file to upload. The format is firstBytePosition-lastBytePosition/totalFileLength where the byte positions are zero-based.
- Content-MD5 (Optional) - See Input Parameters section above.
- Content-Metadata (Optional) - See Input Parameters section above.
Content-Range
The Content-Range header is sent with a partial part of a file to specify where in the full file the partial part should be applied (RFC2616 Section 14.16). It is used to allow two different upload actions.
Partial File Upload
When included with a HTTP upload (/Upload.ashx), it will allow you to upload contiguous portions of a file in multiple requests by providing the range that you will be sending in each request. This allows you to upload extremely large files (file size greater than 2 GB which is the limit of a single HTTP request) by progressively appending content of a file spanning multiple requests rather than sending the entire file in one request. In this case, the Content-Range must adhere to the following guidelines or an error will be returned:
- The first byte position of the very first range must be 0.
- For each subsequent range, the first byte position must be 1 more than the last byte position of the preceding range. You must append the content of the file in order, not randomly.
- The last byte position of the last range must be 1 less than the total file length (since byte position is zero-based.) This signals that the entire file has been uploaded.
- If Content-Range is not provided, it is assumed the entire file will be uploaded in a single request.
Virtual URLs
Virtual URLs allow the use of a customer's own domain or sub-domain to be used as a mask over Nirvanix URLs when making download or operational calls. This is done through a two step process of registering the desired name with Nirvanix using the Nirvanix Management Portal (NMP), and then creating the necessary CNAME records to allow for proper name resolution.
For example, if a customer controls the domain "MyCompany123.com" and would like to use the sub-domain "storage.MyCompany123.com" for all SDN calls, they can simply register the sub-domain in NMP and then create CNAME entries for:
- services.storage.MyCompany123.com
- nodeX.storage.MyCompany123.com - "X" must be replaced with a numeric value for all the nodes in the Nirvanix SDN; details for this are provided in NMP
Once the CNAME entries are propagated, the customer-defined sub-domains can be used in place of the usual Nirvanix sub-domains.
A Nirvanix customer can optionally map a Virtual URL to an existing Application that they manage, or a single Account beneath such an application. A Virtual URL that is mapped to an Application or Account is granted default and restricted access to that Application or Account.
Notes:
- A Virtual URL can only have one mapping. However, a single Application or Account can have several Virtual URLs mapped to it.
Managing Virtual URLs
To use a Virtual URL, the domain or sub-domain must be registered with Nirvanix through NMP. This is required to help prevent URL spoofing.
To do this, login to NMP and browse to the Virtual URLs section under Applications. This page provides all the tools needed to register and customize a Virtual URL with Nirvanix. There you will be presented with the following:
- A form to create new Virtual URLs.
- A list of existing Virtual URLs that can be deleted, or have their mappings reassigned.
Propagation Times
A Virtual URL creation, change, or deletion in NMP may take 5 - 10 minutes to fully propagate to the SDN.
CNAME creations, changes, or deletions generally require 24 - 72 hours for the DNS to propagate completely.
Mapped Zones
All Virtual URLs have some sort of mapping. There are three types of mapping allowed:
- 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.
- 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.
- Account Mapping - The Virtual URL is mapped to a single Account of an Application of the Master Account that registered the Virtual URL. Only the mapped Account can use the URL. This is helpful for sharing publicly hosted files.
*Note: Deleting an Application or Account that has Virtual URLs mapped to it will delete the Virtual URL and you will need to re-create them.
Generating Transfer Paths for Mapped Virtual URLs
The main benefit to mapping a Virtual URL is the ability to customize the access paths to get to individual files. Without mapping, Nirvanix
file paths take this form:
services.nirvanix.com/<Application Name>/<Account Username>/Path to File
A default download link for a hosted file may look like this:
http://services.nirvanix.com/App_Name/Account_Username/file_in_the_root_directory.txt
However, if a customer has the Virtual URL "storage.MyCompany123.com"mapped to an Application, that Application name should not be included in the URL.
The following is a sample URL with Application Mapping:
http://services.storage.MyCompany123.com/Account_Username/File_in_the_root_directory.txt
Similarly, if a customer has the Virtual URL"storage.MyCompany123.com" mapped to an Account, the Application Name and Account Username would not be
included. The following is a sample URL with this type of mapping:
http://services.storage.MyCompany123.com/File_in_the_root_directory.txt
Here are the rules for creating Upload and Download paths:
- Default Mapping - No part of the path is filled in.
- 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.
- Account Mapping - The name of the Application and the username of the Account that the Virtual URL is mapped to is ALWAYS added to the beginning of the path that is provided.
The GetOptimalUrls Web Service can be used to generate a complete download URL which takes advantage of any Virtual URL mapping. Simply make the call to the GetOptimalUrls web method using the Virtual URL, and response back will be formatted correctly with the same Virtual URL used.
*Note: When using a Virtual URL that has Application Mapping, the Application name must not be included in any upload or download links. When using a Virtual URL mapped to an Account, the Application name and Account username must not be included in any upload or download links. Doing either one of these will result in a "Path Not Found" exception.
Using Web Services with Virtual URLs
All Web services actions are fully supported using Virtual URLs, using either the SOAP or REST protocol. There are no changes to the Web Services Interface. Mappings are enforced at login to provide a secure environment.
For example, a customer has the following:
- The following Applications: App1 and App2
- The Virtual URL "storage.MyCompany123.com" mapped to application App1
- An account of App1 with the username "ChildUser1"
- An account of App2 with the username "Child User of Unmapped App"
The customer can use the following URL to login "ChildUser1":
http://services.storage.MyCompany123.com/ws/Authentication/Login.ashx
However "Child User of Unmapped App" cannot log in using the Virtual URL, because that Account does not belong to the Application that is mapped to the Virtual URL. "Child User of Unmapped App" can continue to use the following URL to perform all Web Services calls: http://services.nirvanix.com/ws/Authentication/Login.ashx
These restrictions are enforced to prevent unauthorized accounts from spoofing Virtual URLs.
*Note: When providing paths for IFS operations, the paths are used as provided, with no regards to Virtual URL Mapping. While Mapped Applications and/or Account Usernames are pre-pended to Transfer links, they are NOT pre-pended to Web Services paths. All paths used through web services are used as-is.
Glossary
CNAME - An alias within a DNS referencing a (sub) domain to a separate (sub) domain’s IP address associations. For example, mapping "node1.storage.MyCompany123.com" to "node1.nirvanix.com".
Default Mapping - A domain (e.g. "MyCompany123.com") or sub-domain (e.g. "storage.MyCompany123.com") that has not been mapped to a specific Application or Child Account but is registered in NMP. For example "storage.MyCompany123.com" pointing to "nirvanix.com".
Mapped Zone - A domain (e.g. "MyCompany123.com") or sub-domain (e.g. "storage.MyCompany123.com") that has been mapped to a specific Application or Child Account within the Nirvanix SDN. For example, "storage.MyCompany123.com" pointing to "nirvanix.com/App1/ChildUser1".
API Reference Section
Accounting Namespace
The Accounting Namespace allows users to set and retrieve the limits, contact information, and usage for accounts. These settings control the access to a users files. This component exposes the commands that allow a master account to create child accounts, and set and read their limits.
CreateChildAccount
The CreateChildAccount command creates a child account with the provided username, password, and contact information under a specific Application Key. The provided Session Token must be from the login of the master account. The username must be unique under the Application Key associated with the session token.
Input Parameters
| 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 first name | Optional Length limit: 30 |
| LastName | An account contact last name | Optional Length limit: 30 |
| MiddleInitial | An account contact middle initial | 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: 3 | |
| CountryID | See the appendix for the list of Country IDs. | Optional |
| PostalCode | Optional Length limit: 50 |
Output Values
A ResponseCode is always returned and if successful is a "0". If an error occurs, the ErrorMessage text is also returned.
REST Response XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/CreateChildAccount.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser&password=childpass
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 65004 | InvalidAppKey | Occurs if an invalid AppKey is used or you do not own the AppKey you are attempting to create the child under. |
| 65101 | InvalidContactParameter | Occurs if contact information is incorrect. |
| 65005 | InvalidAccountType | Occurs if non-master Account attempts to create a child. |
| 65006 | DuplicateUserNameUnderAppKey | Occurs if UserName is not unique for an AppKey |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to create a child account. |
| 80101 | InvalidSessionToken | The session token provided is invalid or expired. |
See code samples using our SDKs CreateChildAccount.
DeleteChildAccount
The DeleteChildAccount command deletes the child account that matches the provided username. The provided Session Token must be from the login of the master account and the Application Key provided must be from an application owned by that master account. The username must be under the Application Key associated with the session token. If the username exists under the Application Key, it will be deleted. A Response Code will be returned.
Note: Deleting an account that a Virtual URL is mapped to will delete the Virtual URL and all files in that account.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| SessionToken | A valid session token for the user. | Required |
| Username | The account username. | Required |
Output Values
A ResponseCode is always returned and if successful is a "0". If an error occurs, ErrorMessage is also returned.
REST Response XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/DeleteChildAccount.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to delete the child account. |
| 65009 | DeletedAccount | The account has already been deleted. |
| 80101 | InvalidSessionToken | The session token provided is invalid or expired. |
See code samples using our SDKs DeleteChildAccount.
SetAccountStatus
The SetAccountStatus command allows a child account to be locked or unlocked. The provided Session Token must be from the login of the master account and the Application Key provided must be from an application owned by that master account. The username must be under the Application Key associated with the session token. If the username exists under the Application Key, the status will be modified. A Response Code will be returned.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| SessionToken | A valid session token for the user. | Required |
| Username | The account username. | Required |
| AccountStatus | Valid values are Lock and Unlock. | Required |
Output Values
A ResponseCode is always returned and if successful is a "0". If an error occurs, ErrorMessage is also returned.
REST Response XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/SetAccountStatus.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser&accountStatus=Lock
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to set the child account status. |
| 65104 | UsernameNotFound | The specified username doesn't exist. |
| 80101 | InvalidSessionToken | The session token provided is invalid or expired. |
See code samples using our SDKs SetAccountStatus.
GetAccountUsage
The GetAccountUsage command returns all of the usage metrics for the provided username under the provided Application Key. A Response Code will be returned, as well as a list of usage. The usage returned is based on the creation date of the username you are requesting. Every 30 days the account information is reset back to 0 with the exception of the Total Storage Usage which is a running average of current storage. The 30 day reset is inclusive of the 30th day and the limits are actually reset at the beginning of the 31st day.
Available Features returned in the usage results:
- Download Bandwidth Usage
- Upload Bandwidth Usage
- Total Storage Usage
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| SessionToken | A valid session token for the user. | Required |
| Username | The account username. | Required |
Output Values
A ResponseCode is always returned and if successful is a "0". A successful execution will return the feature name and usage amount. If an error occurs, ErrorMessage is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element ref="FeatureName" minOccurs="0"/>
<xs:element ref="TotalUsageAmount" minOccurs="0"/>
<xs:element ref="UsageStartDate" minOccurs="0"/>
<xs:element ref="UsageEndDate" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
<xs:element ref="FeatureName" minOccurs="0"/>
<xs:element ref="TotalUsageAmount" minOccurs="0"/>
<xs:element ref="UsageStartDate" minOccurs="0"/>
<xs:element ref="UsageEndDate" minOccurs="0"/>
</xs:schema>
Sample REST Request
/ws/Accounting/GetAccountUsage.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?> <Response> <ResponseCode>0</ResponseCode> <GetUsage> <FeatureName>Download Bandwidth Usage</FeatureName> <TotalUsageAmount>1490048</TotalUsageAmount> <UsageStartDate>Sun, 14 Jun 2009 00:00:00 GMT</UsageStartDate> <UsageEndDate>Tue, 14 Jul 2009 22:08:24 GMT</UsageEndDate> </GetUsage> <GetUsage> <FeatureName>Total Storage Usage</FeatureName> <TotalUsageAmount>726181</TotalUsageAmount> <UsageStartDate>Sun, 14 Jun 2009 00:00:00 GMT</UsageStartDate> <UsageEndDate>Tue, 14 Jul 2009 22:08:24 GMT</UsageEndDate> </GetUsage> <GetUsage> <FeatureName>Upload Bandwidth Usage</FeatureName> <TotalUsageAmount>0</TotalUsageAmount> <UsageStartDate>Sun, 14 Jun 2009 00:00:00 GMT</UsageStartDate> <UsageEndDate>Tue, 14 Jul 2009 22:08:24 GMT</UsageEndDate> </GetUsage> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs GetAccountUsage.
GetAccountLimits
The GetAccountLimits command returns all of limits for the account associated with the session token. A Response Code will be returned, as well as a list of the limits. The limit will be returned as "-1" if the specified limit is not set. The IsAppKeyLimit defines if a limit has been set on the entire application rather than just at the account.
Available limits returned in the results:
- StorageAmount - The total bytes stored.
- DownloadBandwidthAmount - The total number of bytes that can be downloaded per pay period.
- FileSizeDownloadLimit - The maximum size in bytes of a file that can be downloaded.
- UploadBandwidthAmount - The total number of bytes that can be uploaded per pay period.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| SessionToken | A valid session token for the user. | Required |
| Username | The master or 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
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage " minOccurs="0"/>
<xs:element ref="Type" minOccurs="0"/>
<xs:element ref="Value" minOccurs="0"/>
<xs:element ref="IsAppKeyLimit" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="ErrorMessage " minOccurs="0"/>
<xs:element ref="Type" minOccurs="0"/>
<xs:element ref="Value" minOccurs="0"/>
<xs:element ref="IsAppKeyLimit" minOccurs="0"/>
</xs:schema>
Sample REST Request
/ws/Accounting/GetAccountLimits.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?> <Response> <ResponseCode>0</ResponseCode> <Limits> <Type>StorageAmount</Type> <Value>100000</Value> <IsAppKeyLimit>false</IsAppKeyLimit> </Limits> <Limits> <Type>DownloadBandwidthAmount</Type> <Value>10000</Value> <IsAppKeyLimit>false</IsAppKeyLimit> </Limits> <Limits> <Type>FileSizeDownloadLimit</Type> <Value>-1</Value> <IsAppKeyLimit>true</IsAppKeyLimit> </Limits> <Limits> <Type>UploadBandwidthAmount</Type> <Value>-1</Value> <IsAppKeyLimit>true</IsAppKeyLimit> </Limits> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs GetAccountLimits.
SetAccountLimits
The SetAccountLimits command sets the limits for the provided username under the provided Application Key. The Session Token must belong to a master Account for the username. All limits are set in bytes and a -1 is used to mark it as unlimited.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| SessionToken | A valid session token for the user. | Required |
| Username | The account username. | Required |
| Type | The feature type. Valid types are:
|
Required |
| 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
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/SetAccountLimits.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser&StorageAmount=10000&FileSizeDownloadLimit=5000
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs SetAccountLimits.
GetAccountInfo
The GetAccountInfo command gets the account details for the account associated with the session token. If the session token being used belongs to the master account a child account can be specified in username. If the session token is from a login of a child account then only that child accounts account info can be retrieved.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| SessionToken | A valid session token for the user. | Required |
| Username | The master or child account to operate on. | Required |
| ContactType | The account contact type. Must be BillableContact or TechnicalContact (default). This is only supported in the REST API. | Optional |
Output Values
A Response Code is always returned. A successful execution will return account contact data. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="GetAccountInfo">
<xs:complexType>
<xs:sequence>
<xs:element name="Contact">
<xs:complexType>
<xs:sequence>
<xs:element ref="FirstName" minOccurs="0"/>
<xs:element ref="LastName" minOccurs="0"/>
<xs:element ref="MiddleInitial" minOccurs="0"/>
<xs:element ref="PhoneNumber" minOccurs="0"/>
<xs:element ref="EmailAddress" minOccurs="0"/>
<xs:element ref="EmailFormat" minOccurs="0"/>
<xs:element ref="AddressLine1" minOccurs="0"/>
<xs:element ref="AddressLine2" minOccurs="0"/>
<xs:element ref="City" minOccurs="0"/>
<xs:element ref="State" minOccurs="0"/>
<xs:element ref="CountryID" minOccurs="0"/>
<xs:element ref="PostalCode" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element ref="UserName" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="ErrorMessage" type="xs:string"/>
<xs:element ref="UserName" type="xs:string"/>
<xs:element ref="FirstName" type="xs:string"/>
<xs:element ref="LastName" type="xs:string"/>
<xs:element ref="MiddleInitial" type="xs:string"/>
<xs:element ref="PhoneNumber" type="xs:string"/>
<xs:element ref="EmailAddress" type="xs:string"/>
<xs:element ref="EmailFormat" type="xs:string"/>
<xs:element ref="AddressLine1" type="xs:string"/>
<xs:element ref="AddressLine2" type="xs:string"/>
<xs:element ref="City" type="xs:string"/>
<xs:element ref="State" type="xs:string"/>
<xs:element ref="CountryID">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="PostalCode" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/GetAccountInfo.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser&ContactType=TechnicalContact
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?> <Response> <ResponseCode>0</ResponseCode> <GetAccountInfo> <Contact> <FirstName>First</FirstName> <LastName>Last</LastName> <MiddleInitial>M</MiddleInitial> <PhoneNumber>123-123-1234</PhoneNumber> <EmailAddress>me@here.now</EmailAddress> <EmailFormat>Text</EmailFormat> <AddressLine1>123 here st.</AddressLine1> <AddressLine2>Unit 11</AddressLine2> <City>Good City</City> <State>CA</State> <CountryID>1</CountryID> <PostalCode>12345</PostalCode> </Contact> <Username>mychilduser</Username> </GetAccountInfo> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | InvalidParameter | Invalid contact, ContactType must be in the list: TechnicalContact, BillingContact. Other parameter problems can cause this error. |
| 65104 | UserNameNotFound | The UserName cannot be found. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs GetAccountInfo.
SetAccountInfo
The SetAccountInfo command changes the account details for the provided username. To set the account information for a child account you must use a session token from the master account for that child or from the login of the child itself.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| Username | Your username or a child user under the current master account / application. | Required |
| FirstName | Optional | |
| LastName | Optional | |
| MiddleInitial | Optional | |
| PhoneNumber | Primary Phone Number | Optional |
| EmailAddress | Optional Length limit: 1000 | |
| EmailFormat | TEXT or HTML | Optional |
| Address1 | Optional Length limit: 200 | |
| Address2 | Optional Length limit: 200 | |
| City | Optional Length limit: 200 | |
| State | Optional Length limit: 2 | |
| CountryID | See Country Code List for Valid values. | Optional |
| PostalCode | Optional Length limit: 50 | |
| ContactType | The account contact type. Must be BillableContact or TechnicalContact (default). This is only supported in the REST API. | Optional |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/SetAccountInfo.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser&firstName=First&lastName=Last&middleInitial=M&phoneNumber=123-123-1234& emailAddress=me@here.now&emailFormat=html&address1=123 Here St.&address2=Unit 11&city=Good City& State=CA&CountryID=1&PostalCode=12345&ContactType=TechnicalContact
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 65101 | InvalidContactException | Occurs when a required contact field is missing Occurs when a contact field is too long Occurs if an email address is not valid |
| 65104 | UserNameNotFound | The UserName cannot be found. |
| 65005 | InvalidAccountType | Occurs if non-master Account attempts to set account info. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs SetAccountInfo.
SetAccountNotes
The SetAccountNotes command sets an XML document stored with the account. The XML must be well formed or it will be rejected. The Session Token must belong to a master Account for the username.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| sessionToken | A valid session token for the user or master account. | Required |
| username | The account username. | Required |
| xmlNotes | Well formed XML document | Required |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/SetAccountNotes.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser&xmlNotes=<xml><note1>Test</note1></xml>
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | InvalidXML | The XML parameter does not contain a valid value. An XML document is considered to be well formed if it meets all the syntactical requirements defined by the World Wide Web Consortium (W3C) Extensible Markup Language (XML) 1.0 Recommendation. |
| 65104 | UserNameNotFound | The UserName cannot be found. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs SetAccountNotes.
GetAccountNotes
The GetAccountNotes command retrieves an XML document stored with the account. This method can only be called by the master account. The standard usage is to provide notes about a child account that are not visible to that child. An XML document will be returned.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| sessionToken | A valid session token for the master account. | Required |
| username | The account username. | Required |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="xmlNotes" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="xmlNotes" type="xs:string"/>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/GetAccountNotes.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> <GetAccountNotes><xml><note1>test</note1></xml></GetAccountNotes> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 65104 | UserNameNotFound | The UserName cannot be found. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get account notes for the child account. |
See code samples using our SDKs GetAccountNotes.
GetStorageUsage
The GetStorageUsage command returns the total storage usage for the account passed in the username. A Response Code will be returned, as well as the total storage in bytes. This can be called by either the master or child account but one child account cannot view another.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| SessionToken | A valid session token for the user. | Required |
| Username | The child account to operate on. | Required |
Output Values
A Response Code is always returned. A successful execution will return the total storage in bytes. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element ref="StorageUsage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element name="StorageUsage">
<xs:simpleType>
<xs:restriction base="xs:long" />
</xs:simpleType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/Accounting/GetStorageUsage.ashx?sessionToken=YOURSESSIONTOKEN &username=mychilduser
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> <StorageUsage>12345678</StorageUsage> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 65104 | UserNameNotFound | The UserName cannot be found. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs GetStorageUsage.
ListChildAccounts
The ListChildAccounts method will retrieve the list of child accounts associated with the specified master account under the current storage pool. This method can only be called by the master account.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the logged in master account. | Required |
| pageNumber | The page number to list. | Required |
| pageSize | The number of child accounts to list for the specified page. The maximum for this value is 500. | Required |
Output Values
A Response Code is always returned. A pages of child accounts will be returned based on the pageSize and pageNumber. If an error occurred, an Error Message is returned.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element ref="Account" minOccurs="0" maxOccurs="500"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element name="Account" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Accounting/ListChildAccounts.ashx?sessionToken=YOURSESSIONTOKEN &pageNumber=1&pageSize=500
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> <Account>childuser1</Account> <Account>childuser2</Account> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 65008 | PageSizeExceedsLimit | If you pass a page size greater than 500. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs ListChildAccounts.
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 topTranscode
The Transcode method is used to convert an audio file from one format to another.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFilePath | The audio file to be transcoded. | Required |
| destFilePath | 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. | Required |
| callbackURL | The URL to be invoked when the transcode operation has been completed. | Optional |
| options |
The available options are:
RESTEach option is passed as a separate parameter. Ex: &numberOfFrames=10000&biteRate=192
SOAPA string array of ':' delimited parameters. Ex: "numberOfChannels:100". |
Optional |
Output Values
A result code with the status of the transcode command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual transcode operation was successful.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Audio/Transcode.ashx?sessionToken=YOURSESSIONTOKEN &srcFilePath=mysong.mp3&destFilePath=mynewsong.wav&numberOfFrames=10000&bitRate=192000 &callbackURL=http://www.yoursite.com/callbackhandler.php
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Callback Response
When provided a callback will be made to a web server you have defined. The request will be made with a HTTP GET.
http://www.yoursite.com/callbackhandler.php?NVX.returnCode=00000 &NVX.errorMessage=Error Message for Audio Transcode.
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 101 | Invalid Parameter | Invalid parameter information was provided with the request. |
| 70002 | FileNotFound | The source file path specified does not exist. |
| 70004 | AlreadyExists | The destination file path specified already exists. |
| 70005 | InvalidPath | The source or destination path specified is invalid. |
| 70009 | PathTooLong | The destination file path specified is longer than the maximum allowed. |
| 70026 | FileLocked | The source or destination file is locked, try again at a later time. |
| 70027 | FolderLocked | The destination folder is locked, try again at a later time. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
| 80015 | OutOfBytes | The operation could not be completed because you have reached your file storage limit. |
| 80021 | StorageLimitExceeded | The operation could not be completed because you have reached your file storage limit. |
See code samples using our SDKs Audio Transcode.
Authentication Namespace
The Authentication namespace is used to allow connections into the system. Every connection must first retrieve a session token from the login method. This will allow you to authenticate using a single accounts username and password under a single application.
Login
The Login method is used to login to the system and generate a Session Token restricted to the caller's IP address.
Input Parameters
| 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
A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element ref="SessionToken" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
<xs:element name="SessionToken" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Authentication/Login.ashx?appKey=YOURAPPKEY&userName=testuser&password=Abc123
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> <SessionToken>6dfa5a15-a4e1-4e9a-9c0e-0cf4299936af</SessionToken> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs Login.
LoginProxy
The LoginProxy method is used to login to the system on behalf of another consumer and generate a Session Token restricted to that consumer's IP address.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| appKey | The application key that contains the user to be logged in. | Required |
| userName | The account name to log in with. | Required |
| password | The password for the account. | Required |
| consumerIP | The consumer's IP address. | Required |
Output Values
A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element ref="SessionToken" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
<xs:element name="SessionToken" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Authentication/LoginProxy.ashx?appKey=YOURAPPKEY&userName=testuser &password=Abc123&consumerIP=123.123.123.123
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> <SessionToken>6dfa5a15-a4e1-4e9a-9c0e-0cf4299936af</SessionToken> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs LoginProxy.
Logout
The Logout method removes a session token from use. This is primarily used for security so when you are finished with a session token it cannot be used by anyone else. This will also allow you to switch the session token when combined with the login if the account is in continuous use such as a background processing application.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | The session token that represents the user to be logged out. | Required |
Output Values
A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Authentication/Logout.ashx?sessionToken=YOURSESSIONTOKEN
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs Logout.
ChangePassword
The ChangePassword is used to change an accounts own password.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| appKey | The application key that contains the user to change. | Required |
| userName | The account name to change. | Required |
| oldPassword | The old password for the account. | Required |
| newPassword | The new password to change to. | Required |
Output Values
A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Authentication/ChangePassword.ashx?appKey=YOURAPPKEY &userName=testuser&oldPassword=Abc123&newPassword=Def456
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs ChangePassword.
SetChildAccountPassword
The SetChildAccountPassword is used by a master account to set a child accounts password.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| appKey | The application key that contains the user to change. | Required |
| userName | The master account name. | Required |
| password | The password for the master account. | Required |
| childAccountUsername | The child account name to set the password. | Required |
| childAccountPassword | The child account password to set to. | Required |
Output Values
A Response Code is always returned. A successful execution will return a session token that can be used to call other services functions in the SDN. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Authentication/SetChildAccountPassword.ashx?appKey=YOURAPPKEY &userName=MasterUser&password=Abc123&childAccountUsername=testuser&childAccountPassword=Def456
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs SetChildAccountPassword.
Image Namespace
For Nirvanix Web Services 1.0 the Image component currently consists of taking an image in your file system and resizing it. This is useful, for example, in resizing images dynamically for displaying on different device-types, or rendering display thumbnails of large images uploaded by users.
Resize
The Resize method is used to resize an existing image. A new image will be created as a result and put into your file system.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFilePath | The path to the image file. | Required |
| destFilePath | The path to the destination image file. Image format conversions occur automatically based on the suffix of this file. i.e. .bmp | Required |
| width | The width of the new image. May be set to -1 if you want the width to be calculated based on the aspect ratio of the original image. Both width and height cannot be set to -1. | Required |
| height | The height of the new image. May be set to -1 if you want the height to be calculated based on the aspect ratio of the original image. Both width and height cannot be set to -1. | Required |
| callbackURL | The URL to be invoked when the image resizing has been completed. | Optional |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned. A callback will be made when the resize is completed or has an error.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Image/Resize.ashx?sessionToken=YOURSESSIONTOKEN&srcFilePath= Folder/subfolder/samplefile.jpg&destFilePath=MyResizedImages/samplefileResized.gif &width=320&height=640&callbackURL=http://www.yousite.com/callbackhandler.php
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Callback Response
When provided a callback will be made to a web server you have defined. The request will be made with a HTTP GET.
http://www.yoursite.com/callbackhandler.php?NVX.returnCode=00000 &NVX.errorMessage=Error Message for Image Resize.
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs Image Resize.
RotateFlip
The RotateFlip method is used to rotate or flip an existing image. A new image will be created as a result and put into your file system.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFilePath | The path to the image file. | Required |
| destFilePath | The path to the destination image file. Image format conversions occur automatically based on the suffix of this file. i.e. .bmp | Required |
| rotate | The number of degrees to rotate the image.
Valid values are: RotateNone, Rotate90, Rotate180, Rotate270 |
Required |
| flip | The type of flip manipulation of the image.
Valid values are: FlipNone, FlipHorizontal, FlipVertical, FlipHorizontalVertical |
Required |
| callbackURL | The URL to be invoked when the image rotation/flip has been completed. | Optional |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned. A callback will be made when the RotateFlip is completed or has an error.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Image/RotateFlip.ashx?sessionToken=YOURSESSIONTOKEN&srcFilePath= Folder/subfolder/samplefile.jpg&destFilePath=MyNewImages/samplefileRotated.gif &rotate=Rotate90&flip=FlipHorizontal&callbackURL=http://www.yoursite.com/callbackhandler.php
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Callback Response
When provided a callback will be made to a web server you have defined. The request will be made with a HTTP GET.
http://www.yoursite.com/callbackhandler.php?NVX.returnCode=00000 &NVX.errorMessage=Error Message for Image RotateFlip.
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80003 | AccessDenied | This error is returned if the logged in account is not allowed to get usage for the child account. |
See code samples using our SDKs Image RotateFlip.
Internet File System (IFS) Namespace
All file system operations require the caller to be authenticated. Therefore, all IFS calls require a session token which can be obtained by the Login call. In general, paths can be specified as either absolute or relative to the accounts root folder. For example, if the caller logged in with application key "12345678-ABCD-1234-1234-ABCD12345678" and account name "admin" then the following paths are equivalent:
Absolute: //12345678-ABCD-1234-1234-ABCD12345678/admin/web/index.html12345678-ABCD-1234-1234-ABCD12345678
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 IFS calls may potentially result in a set of common errors. The following table lists these common errors. Each IMFS method may also define additional errors specific to that call.
Common IMFS Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
The following are the Web Service interfaces for IMFS.
CopyFiles
The CopyFiles method is used to copy a file from one location to another. The CopyFiles method can be used to copy one or more files to a given folder. When files are copied, all metadata associated with the original file is also associated with the copied file.
CopyFiles is asynchronous, so a success response does not mean the copy has completed. There is no good way to determine when a copy has completed. Subsequent commands that access the source or destination of the copy before it completes will fail with 70026 File Locked, 70027 Folder Locked, or 70005 Invalid Path. These commands are: Upload (overwrite existing file), RenameFiles, RenameFolders, MoveFiles, MoveFolders, CopyFiles, CopyFolders, DeleteFiles, DeleteFolders. The solution is using retry logic for the 3 errors on each of these commands. Retry logic has the potential to be extremely abusive to the SDN if not done correctly (i.e. retrying in tight loop forever with no sleeps). To be nice, you need to use incremental increasing sleep time between retries (e.g, 1, 2, 4, 8... to max of 60 seconds). The initial sleep time should be roughly based on how large your copy operation is.
The maximum size for any path is 512 characters. If a file is copied into a folder and the resulting file path is more that 512 characters long, the file will become unusable. Any attempt to access or rename this file, or list the contents of the parent folder will result in the following error: 70009 - Path is longer than the maximum allowable length of 512.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFilePath | The path to the file to be copied. More than one file can be specified using a multiple instance of this parameter. | Required |
| destFolderPath | The path to the folder where the items will be copied to. The name of the item is not included in the destination folder. | Required |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/CopyFiles.ashx?sessionToken=YOURSESSIONTOKEN &srcFilePath=Folder/subfolder/samplefile.txt&destFolderPath=Folder/subfolder/DestFolder
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs 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.
CopyFolders is asynchronous, so a success response does not mean the copy has completed. There is no good way to determine when a copy has completed. Subsequent commands that access the source or destination of the copy before it completes will fail with 70026 File Locked, 70027 Folder Locked, or 70005 Invalid Path. These commands are: Upload (overwrite existing file), RenameFiles, RenameFolders, MoveFiles, MoveFolders, CopyFiles, CopyFolders, DeleteFiles, DeleteFolders. The solution is using retry logic for the 3 errors on each of these commands. Retry logic has the potential to be extremely abusive to the SDN if not done correctly (i.e. retrying in tight loop forever with no sleeps). To be nice, you need to use incremental increasing sleep time between retries (e.g, 1, 2, 4, 8... to max of 60 seconds). The initial sleep time should be roughly based on how large your copy operation is.
The maximum size for any path is 512 characters. When a folder is copied into another folder any resulting file path that is more that 512 characters long will become unusable. Any attempt to access or rename this file or folder, or list the contents of the parent folder, will result in the following error: 70009 - Path is longer than the maximum allowable length of 512.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFolderPath | The folders to be copied. More than one folder may be specified using multiple instances of this parameter. | Required |
| destFolderPath | The path to the folder where the items will be copied to. | Required |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/CopyFolders.ashx?sessionToken=YOURSESSIONTOKEN& srcFolderPath=Folder/subfolder/FolderToCopy&destFolderPath=Folder/subfolder/DestFolder
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs CopyFolders.
CreateFolders
The CreateFolders method is used to create one or more folders at the specified location.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| folderPath | The path to the folder to be created. More than one folder may be specified using multiple instances of this parameter. The path cannot be set to . or .. | Required |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/CreateFolders.ashx?sessionToken=YOURSESSIONTOKEN &folderPath=Folders/subfolder/NewFolder/1&folderPath=Folders/subfolder/NewFolder2
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs CreateFolders.
DeleteFiles
The DeleteFiles method is used to remove one or more files. There may be a slight delay after a file is deleted before it unavailable for download.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| filePath | The path to the file to be deleted. One or more files may be specified using multiple instances of this parameter. | Required |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/DeleteFiles.ashx?sessionToken=YOURSESSIONTOKEN &filePath=Folders/subfolder/myfile.txt
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs DeleteFiles.
DeleteFolders
The DeleteFolders method is used to remove one or more folders. Folders will be deleted even if they contain files.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| folderPath | The path to the folder to be deleted. One or more folders may be specified using multiple instances of this parameter. | Required |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/DeleteFolders.ashx?sessionToken=YOURSESSIONTOKEN &folderPath=Folders/subfolder
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs DeleteFolders.
GetPathInfo
The GetPathInfo method is used to retrieve information about an existing file or folder. It provides some basic information about the item, such as the file size, whether the path is a file or folder, metadata, tags, created date, and last modification date.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| itemPath | The path to the file or folder. | Required |
| showMetadata | A flag to determine whether or not metadata is returned. | Optional |
| showTags | A flag to determine whether or not tags are returned. | Optional |
| showIsShared | A flag to determine whether or not the information related to the item being shared is returned. | Optional |
| metadataOutput | The metadata output format. Valid values are 'xml' and 'json'. Defaults to 'xml'. | Optional |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="GetPathInfo">
<xs:complexType>
<xs:sequence>
<xs:element ref="ItemName" minOccurs="0"/>
<xs:element ref="IsFile" minOccurs="0"/>
<xs:element ref="CreatedDate" minOccurs="0"/>
<xs:element ref="SizeBytes" minOccurs="0"/>
<xs:element ref="FileType" minOccurs="0"/>
<xs:element name="MetaData">
<xs:complexType>
<xs:sequence>
<xs:element ref="Data" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element ref="Tags" minOccurs="0"/>
<xs:element ref="IsShared" minOccurs="0"/>
<xs:element ref="ModifiedDate" minOccurs="0"/>
<xs:element ref="ItemID" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="ItemName" type="xs:string"/>
<xs:element ref="IsFile" type="xs:boolean"/>
<xs:element ref="CreatedDate" type="xs:string"/>
<xs:element ref="SizeBytes">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="FileType" type="xs:string"/>
<xs:element ref="Data" type="xs:string"/>
<xs:element ref="Tags" type="xs:string"/>
<xs:element ref="IsShared" type="xs:boolean"/>
<xs:element ref="ModifiedDate" type="xs:string"/>
<xs:element ref="ItemID" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/GetPathInfo.ashx?sessionToken=YOURSESSIONTOKEN &itemPath=DirTest/F8.jpg&showMetadata=true&showTags=false&showIsShared=true
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?> <Response> <ResponseCode>0</ResponseCode> <GetPathInfo> <ItemName>F8.jpg</ItemName> <IsFile>true</IsFile> <CreatedDate>Mon, 09 Mar 2009 02:10:33 GMT</CreatedDate> <SizeBytes>566534</SizeBytes> <FileType>Image</FileType> <Metadata> <Metadata FileName="F8.jpg"> <Data Key="Height">960</Data> <Data Key="MD5">vFDnR6xvVvIYJS64vuRL9A==</Data> <Data Key="Width">1280</Data> </Metadata> </Metadata> <Tags /> <IsShared>true</IsShared> <ModifiedDate>Mon, 09 Mar 2009 02:11:07 GMT</ModifiedDate> <ItemID>16959956610088753346</ItemID> </GetPathInfo> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs GetPathInfo.
ListFolder
The ListFolder method is used to describe the contents of a folder. It lists the files and folders as well as some basic information about the items, such as the file size, metadata, tags and created date. This call supports paging.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| folderPath | The path to the folder to be listed. If not specified, the logged in accounts root folder will be listed. | Required |
| pageNumber | The page number to list. | Required |
| pageSize | The size of the page to return. This can be a maximum of 500 items (this is for files and folders combined per call). | Required |
| sortCode | The sorting criteria. Must be one of the following: Name, CreatedDate, SizeBytes, FileType. By default, listing will be sorted by Name. Also regardless of the sorting criteria, all folders will be grouped together and all files will be grouped together. | Optional |
| sortDescending | Flag to indicate whether the sorting should be in descending order. Set to true if descending order is desired. By default the sorting order is descending. | Optional |
| showMetadata | A flag to determine whether or not metadata is returned. By default the metadata will be returned. | Optional |
| showTags | A flag to determine whether or not tags are returned. By default the tags will not be returned. | Optional |
Output Values
| Name | Description |
|---|---|
| ResponseCode | A result code with the status of the ListFolder request. The code will be 0 if the method is successful or one of the error codes below if an error occurs. |
| ListFolder | The requested page of folder content if the response code is 0. |
| ErrorMessage | The error message if the response code is not 0. |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element name="ListFolder">
<xs:complexType>
<xs:sequence>
<xs:element ref="TotalFolderCount" minOccurs="1"/>
<xs:element ref="TotalFileCount" minOccurs="1"/>
<xs:element ref="PageFolderCount" minOccurs="1"/>
<xs:element ref="PageFileCount" minOccurs="1"/>
<xs:element ref="Folder" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element ref="FolderCount" minOccurs="1"/>
<xs:element ref="FileCount" minOccurs="1"/>
<xs:element ref="Name" minOccurs="1"/>
<xs:element ref="Path" minOccurs="1"/>
<xs:element ref="CreatedDate" minOccurs="1"/>
<xs:element ref="MetaData" minOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element ref="Data" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element ref="FileTags" minOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element ref="File" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element ref="SizeBytes" minOccurs="1"/>
<xs:element ref="Name" minOccurs="1"/>
<xs:element ref="Path" minOccurs="1"/>
<xs:element ref="CreatedDate" minOccurs="1"/>
<xs:element ref="MetaData" minOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element ref="Data" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element ref="FileTags" minOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="TotalFolderCount">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="TotalFileCount">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="PageFolderCount">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="PageFileCount">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="FolderCount">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="FileCount">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="Name" type="xs:string"/>
<xs:element ref="Path" type="xs:string"/>
<xs:element ref="CreatedDate" type="xs:string"/>
<xs:element ref="SizeBytes">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element ref="Data" type="xs:string"/>
<xs:element ref="FileTags" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/ListFolder.ashx?sessionToken=YOURSESSIONTOKEN &folderPath=DirTest/F8&pageNumber=1&pageSize=5&sortCode=Name&sortDescending=false
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<ResponseCode>0</ResponseCode>
<ListFolder>
<TotalFolderCount>3</TotalFolderCount>
<TotalFileCount>312509</TotalFileCount>
<PageFolderCount>3</PageFolderCount>
<PageFileCount>2</PageFileCount>
<Folder>
<FolderCount>0</FolderCount>
<FileCount>1</FileCount>
<Name>F8AChild</Name>
<Path>DirTest/F8/F8AChild</Path>
<CreatedDate>Wed, 02 May 2007 13:36:41 GMT</CreatedDate>
<Metadata/>
<FileTags>these|are|my|tags</FileTags>
</Folder>
<File>
<SizeBytes>1000000</SizeBytes>
<Name>100000-somefile.txt</Name>
<Path>DirTest/F8/100000-somefile.txt</Path>
<CreatedDate>Wed, 02 May 2007 15:14:14 GMT</CreatedDate>
<Metadata>
<MetaData FileName="100000-somefile.txt">
<Data Key="MD5">tsDn43abFtxCSTdvuRA2BA==</Data>
</MetaData>
</Metadata>
<FileTags></FileTags>
</File>
<File>
<SizeBytes>566534</SizeBytes>
<Name>DSC05829.JPG</Name>
<Path>DirTest/F8/DSC05829.JPG</Path>
<CreatedDate>Tue, 01 Sep 2009 21:55:31 GMT</CreatedDate>
<Metadata>
<MetaData FileName="DSC05829.JPG">
<Data Key="Width">1280</Data>
<Data Key="Height">960</Data>
<Data Key="MD5">vFDnR6xvVvIYJS64vuRL9A==</Data>
</MetaData>
</Metadata>
<FileTags></FileTags>
</File>
</ListFolder>
</response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs 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. If the destination folder specified by destFolderPath does not exist it will be created before moving the files.
The maximum size for any path is 512 characters. If a file is moved into a folder and the resulting file path is more that 512 characters long, the file will become unusable. Any attempt to access or rename this file, or list the contents of the parent folder will result in the following error: 70009 - Path is longer than the maximum allowable length of 512. If an array of parameters is passed and there is an error while processing those paths the entire call will be rolled back. If folders were created for some of the paths provided they will not be removed after the error has occurred.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFilePath | The path to the file to be move. More than one file can be specified using multiple instances of this parameter. | Required |
| destFolderPath | The path to the folder where the items will be moved to. The name of the item is not included in the destination folder. This path cannot include a folder named . or .. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the move. If the result is 0 the method was successful. | 0 |
Output Values
A Response Code is always returned. If an error occurred, an Error Message is returned.
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/MoveFiles.ashx?sessionToken=YOURSESSIONTOKEN &srcFilPath=Folder/subfolder/samplefile.txt&destFolderPath=Folder/subfolder/DestFolder
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs MoveFiles.
MoveFolders
The MoveFolders method is used to move a folder from one location to another. The MoveFolders method can be used to move one or more folders.
The maximum size for any path is 512 characters. When a folder is copied into another folder any resulting file path that is more that 512 characters long will become unusable. Any attempt to access or rename this file or folder, or list the contents of the parent folder will result in the following error: 70009 - Path is longer than the maximum allowable length of 512.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFolderPath | The folders to be moved. More than one folder may be specified using multiple instances of this parameter. | Required |
| destFolderPath | The path to the folder where the items will be moved to. This path cannot include a folder named . or .. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the move. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/MoveFolders.ashx?sessionToken=YOURSESSIONTOKEN &srcFolderPath=Folder/subfolder/FolderToCopy&destFolderPath=Folder/subfolder/DestFolder
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs MoveFolders.
RenameFile
The RenameFile method is used to rename a file from one name to another.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| filePath | The path to the file to be renamed. | Required |
| newFileName | The name of the new file. The file name cannot be . or .. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the rename. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/RenameFile.ashx?sessionToken=YOURSESSIONTOKEN &filePath=Folder/subfolder/samplefile.txt&newFileName=mynewfile.txt
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs RenameFile.
RenameFolder
The RenameFolder method is used to rename a folder from one name to another.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| folderPath | The path to the folder to be renamed. | Required |
| newFolderName | The name of the new folder. The new folder cannot be named . or .. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the rename. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/RenameFolder.ashx?sessionToken=YOURSESSIONTOKEN &folderPath=Folder/subfolder/myfolder&newFolderName=mynewfolder
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs when a folder or file path doesn't exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs RenameFolder.
GetDownloadNodes
The GetDownloadNodes method is used to obtain the current optimum download nodes for one or more files. When passing in more than one path the array returned will be returned in the same order as the paths you have passed in input parameters. Although the download location for each file is subject to change, this should rarely happen. Some of the events that would cause a change are:
- The file has been cached at another node closer to the user.
- The file has been removed from the node due to lack of access.
- The node temporarily cannot serve the file due to hardware failure.
- The node is down for maintenance.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| filePath | The path to the file to download. More than one may be specified using multiple instances of this parameter. | Required |
| excludedNode | Do not return this unreachable storage node. See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for usage details. May specify this parameter more than once (e.g. &excludedNode=node1&excludedNode=node2). | Optional |
Output Values
| Name | Description |
|---|---|
| ResponseCode | A result code with the status of the request. The code will be 0 if the method is successful or one of the error codes below if an error occurs. |
| DownloadNode | The corresponding download nodes if the response code is 0. |
| ErrorMessage | The error message if the response code is not 0. |
REST XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="ResponseCode" type="xs:integer" />
<xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
<xs:element name="DownloadNode" maxOccurs="unbounded" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/IMFS/GetDownloadNodes.ashx?sessionToken=YOURSESSIONTOKEN &filePath=My%20Folder/My%20File%201.txt
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?> <Response> <ResponseCode>0</ResponseCode> <DownloadNode>node1.nirvanix.com</DownloadNode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70002 | File not found | Occurs if any of the files does not exist. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 70205 | No route to SDN | Occurs when use of excludedNode parameters results in no suitable nodes to use. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs 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. Due to the nature of the SDN and the ability to move files to other locations around the world, the expiration time should be set as low as possible for your particular application. This ensures that if there is a problem with a node you will always be able to access your files. Should the file become unavailable you should request a new download URL to get the file from an alternate location on the SDN.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| filePath | The path to the file to download. More than one may be specified using multiple instances of this parameter. | Required |
| expiration | The links time to expiration in seconds. | Required |
| consumerIP | The IP address of the web client which the link is best suited for. | Optional |
| ipRestricted | Boolean determining whether the link is restricted to the consumerIP. | Optional |
| excludedNode | Do not return this unreachable storage node. See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for usage details. May specify this parameter more than once (e.g. &excludedNode=node1&excludedNode=node2). | Optional |
Output Values
| Name | Description |
|---|---|
| ResponseCode | A result code with the status of the request. The code will be 0 if the method is successful or one of the error codes below if an error occurs. |
| Download | The corresponding download link information if the response code is 0. |
| Download/FilePath | The relative Nirvanix path to the file. |
| Download/DownloadHost | The host where the file can be downloaded. This normally corresponds to a node server name. |
| Download/DownloadToken | The token that can be used to download the file. This token is set to expire after the provided expiration time. |
| Download/DownloadURL | The full URL including download token and the node server. This is a direct link to download the file requested. |
| ErrorMessage | The error message if the response code is not 0. |
REST XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="ResponseCode" type="xs:integer" />
<xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
<xs:element name="Download" maxOccurs="unbounded " />
<xs:complexType>
<xs:sequence>
<xs:element name="FilePath" type="xs:string" />
<xs:element name="DownloadHost" type="xs:string" />
<xs:element name="DownloadToken" type="xs:string" />
<xs:element name="DownloadURL" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/IMFS/GetOptimalUrls.ashx?sessionToken=YOURSESSIONTOKEN &filePath=My%20Folder/My%20File%201.txt&expiration=300
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<ResponseCode>0</ResponseCode>
<Download>
<FilePath>My Folder/My File 1.txt</FilePath>
<DownloadHost>node1.nirvanix.com</DownloadHost>
<DownloadToken>
Goh7ot5p~BeuoQ45icq~L9TM2Ksh~xT3bfBueAT~Ocp_3AE
</DownloadToken>
<DownloadURL>
http://node1.nirvanix.com/Goh7ot5p~BeuoQ45icq~L9TM2Ksh~xT3bfBueAT~Ocp_3AE/My%20Folder/My%20File%201.txt
</DownloadURL>
</Download>
</Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70005 | Invalid path | Occurs if any of the files do not exist or a if a folder was passed in. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 70205 | No route to SDN | Occurs when use of excludedNode parameters results in no suitable nodes to use. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDK's 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.
Note: A question that often comes up is the size of the download passed to the GetStorageNode and GetStorageNodeExtended when using a web client to upload. In these instances you will not know the size ahead of time and should instead use the best guess for the file size such as the average file size for you.
Note: that reuse of a upload token can lead to corruption or collisions and every upload should use its own token.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| sizeBytes | The size of the file to be uploaded in bytes. | Required |
| consumerIP | The IP address for the machine that will make the upload. The default is the IP address of the machine making this call. | Optional |
| ipRestricted | True if the upload token should be restricted to the consumerIP. The default is true. | Optional |
| destFolderPath | The folder path that any uploads using the provided upload token must be uploaded into. | Required |
| fileOverwrite | True if a file with the same name in the destination folder should be overwritten by a file uploaded using the upload token. If this value is false, name collisions will result in an upload error. The default is false. | Optional |
| firstByteExpiration | The number of seconds the upload token has until the first byte of an upload is transferred. The default value is for 10 minutes. 0 means use the default value. This value is not enforced using AppendFile in SOAP or UploadFile in SOAP. |
Optional |
| lastByteExpiration | The number of seconds the upload token has until an upload is completed. The default value is for 3 days. 0 means use the default value. | Optional |
Output Values
| Name | Description |
|---|---|
| ResponseCode | A result code with the status of the request. The code will be 0 if the method is successful or one of the error codes below if an error occurs. |
| UploadHost | The server to upload to. |
| UploadToken | An access token to pass into one of the upload methods when performing an upload. |
| ErrorMessage | The error message if the response code is not 0. |
REST XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="ResponseCode" type="xs:integer" />
<xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
<xs:element name="GetStorageNode">
<xs:complexType>
<xs:sequence>
<xs:element name="UploadHost" maxOccurs="1" />
<xs:element name="UploadToken" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/IMFS/GetStorageNodeExtended.ashx?sessionToken=YOURSESSIONTOKEN& sizeBytes=450000&consumerIP=127.0.0.1&ipRestricted=true&destFolderPath=/& fileOverwrite=true&firstByteExpiration=6000&lastByteExpiration=259200
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<ResponseCode>0</ResponseCode>
<GetStorageNode>
<UploadHost>node1.nirvanix.com</UploadHost>
<UploadToken>kMHib15S~c_5IY1CphI~7cFRwvOB~E5evmH0CaL~WccWTQ_Vbu0yJGctig</UploadToken>
</GetStorageNode>
</Response>
Errors
| 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. |
| 70205 | No route to SDN | Occurs when use of excludedNode parameters results in no suitable nodes to use. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs 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. The token expiration for the first byte is 10 minutes, the last byte is 3 days. Also see GetStorageNodeExtended
Note: A question that often comes up is the size of the download passed to the GetStorageNode and GetStorageNodeExtended when using a web client to upload. In these instances you will not know the size ahead of time and should instead use the best guess for the file size such as the average file size for you.
Note: that reuse of a upload token can lead to corruption or collisions and every upload should use its own token.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| sizeBytes | The size of the file to be uploaded in bytes. | Required |
| restrictedIP | The restricted IP address. | Optional |
| excludedNode | Do not return this unreachable storage node. See document Best Practices for Nirvanix API Development at http://developer.nirvanix.com/files/folders/api_developers_guide/default.aspx for usage details. May specify this parameter more than once (e.g. &excludedNode=node1&excludedNode=node2). | Optional |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the rename. If the result is 0 the method was successful. | 0 |
| UploadHost | The server to upload to. | node1.nirvanix.com |
| UploadToken | An upload token to pass into one of the upload methods. | ASDF123DASD |
REST XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="ResponseCode" type="xs:integer" />
<xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
<xs:element name="GetStorageNode">
<xs:complexType>
<xs:sequence>
<xs:element name="UploadHost" maxOccurs="unbounded" />
<xs:element name="UploadToken" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/IMFS/GetStorageNode.ashx?sessionToken=YOURSESSIONTOKEN&sizeBytes=1024
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<ResponseCode>0</ResponseCode>
<GetStorageNode>
<UploadHost>node1.nirvanix.com</UploadHost>
<UploadToken>myuploadtoken</UploadToken>
</GetStorageNode>
</Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs GetStorageNode.
SearchFileSystem
The SearchFileSystem method is used to search for items in your file system that match the specified search criteria.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| username | The username of the account to be searched. | Required |
| searchTerm | The search string to look for files and folders. The '*' character may be used at the beginning or end of the string to support wild card searches. The '_' is also considered a wildcard character. | Required |
| fileType | The file type to search for. Valid types are 'Unassigned', 'Document', 'Executable', 'Audio', 'Video', 'Image'. Passing 'null' means to allow any file type in the search results. | Optional |
| minFileSize | The minimum file size to search for. Should be set to 0 when searching for folders. | Required |
| maxFileSize | The maximum file size to search for. Should be set to 0 when searching for folders. | Required |
| minCreatedDate | The minimum created date for files. | Required |
| maxCreatedDate | The maximum created date for files. | Required |
| maxResults | The maximum number of results to return. The maximum for this value is 10000. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the search. If the result is 0 the method was successful. | 0 |
| SearchCount | The number of results returned in the search. | 15 |
| CreatedDate | The date the item was added to the file system. | 9/1/2007 |
| FileType | The type of file. | Audio |
| IsFile | A flag to indicate whether the item is a file or folder. | True |
| ItemName | The name of the file or folder. | Myimage.jpg |
| ItemPath | The fully qualified path to the file or folder. | MyFolder/MyImage.jpg |
| SizeBytes | The size of the file. 0 if the item is a folder. | 123456 |
REST XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="ResponseCode" minOccurs="1" type="xs:integer" />
<xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="SearchCount" minOccurs="1" type="xs:integer" />
<xs:element name="Item" minOccurs="0" maxOccurs="10000" >
<xs:complexType>
<xs:sequence>
<xs:element name="ItemPath" minOccurs="1" type="xs:string" />
<xs:element name="ItemName" minOccurs="1" type="xs:string" />
<xs:element name="CreatedDate" minOccurs="1" type="xs:string" />
<xs:element name="SizeBytes" minOccurs="1" type="xs:integer" />
<xs:element name="FileType" minOccurs="1" type="xs:string" />
<xs:element name="IsFile" minOccurs="1" type="xs:boolean" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/IMFS/SearchFileSystem.ashx?sessionToken=YOURSESSIONTOKEN &username=myuser&fileType=Video&minFileSize=0&maxFileSize=100000000 &minCreatedDate=7/1/2007&maxCreatedDate=9/1/2007&maxResults=1000
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<ResponseCode>0</ResponseCode>
<SearchResults>
<SearchCount>1</SearchCount>
<Item>
<ItemPath>joebriggs.avi</ItemPath>
<ItemName>joebriggs.avi</ItemName>
<CreatedDate>Wed, 12 Sep 2007 11:06:46 GMT</CreatedDate>
<SizeBytes>7283012</SizeBytes>
<FileType>Video</FileType>
<IsFile>true</IsFile>
</Item>
</SearchResults>
</Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs SearchFileSystem.
Sideload
The Sideload command allows a user to load remote content into their Nirvanix file system. When submitting the targetURL for sideloading it will be placed in a queue and the response will signal that the item has been successfully placed in the queue. This does not mean that the sideload has completed but that it has been successfully scheduled. To get the results of the actual sideload event you will need to provide a callback URL. When the sideload URL has been processed the results will be sent to the callback URL specified with a success result or error message and code.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| targetURL | The URL to retrieve the remote content from. | Required |
| destFilePath | The Nirvanix file system path to store the remote content. | Required |
| callbackURL | The URL to be invoked when the sideload operation has been completed. | Required |
| fileOverwrite | A flag to determine whether the file should be overwritten. Defaults to 'false'. | Optional |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the sideload. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/IMFS/Sideload.ashx?sessionToken=YOURSESSIONTOKEN &targetURL=http://mywebsite.com/default.html&destFilePath=mywebpages/default.html
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs Sideload.
Metadata Namespace
Nirvanix Web Services implements the industry standard REST and SOAP protocols allowing end users to upload, copy, move, and delete files and folders. Furthermore, end users can retrieve a listing of their files and also associate user-defined tags and metadata.
Metadata refers to a specific type of information about a specific type of file. Nirvanix Web Services supports any type of metadata.
The Nirvanix Web Services API provides both a REST and SOAP interface for manipulating metadata. The following standard metadata types are supported; however you can create any type of metadata you desire:
- Width
- Height
- Duration
- BitRate
- FrameRate
- Title
- Artist
- Album
- Genre
- Track
- IsVariableBitRate
DeleteAllMetadata
The DeleteAllMetadata method is used to remove all metadata from a file or folder. Please note that the MD5 metadata type will NOT be removed with this call.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to have all metadata removed. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the metadata delete. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/DeleteAllMetadata.ashx?sessionToken=YOURSESSIONTOKEN &path=Folders/subfolder/myfile.txt
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs DeleteAllMetadata.
DeleteMetadata
The DeleteMetadata method is used to remove specified metadata from a file or folder.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to have all metadata removed. | Required |
| metadata | The types of metadata to be deleted. More than one type may be specified using multiple instances of this parameter. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the metadata delete. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/DeleteMetadata.ashx?sessionToken=YOURSESSIONTOKEN &path=Folders/subfolder/myfile.txt&metadata=Width
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70009 | Path too long | Occurs when the total length of a relative path exceeds the maximum length of 512 characters. |
| 70010 | File/Folder name too long | Occurs when a file or folder name exceeds the maximum length of 256 characters. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs DeleteMetadata.
GetMetadata
The GetMetadata method is used to retrieve all metadata from a file or folder.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to have all metadata retrieved. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the metadata get. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element name="Metadata" minOccurs="0" >
<xs:complexType>
<xs:sequence>
<xs:element ref="Type" minOccurs="1" type="xs:string"/>
<xs:element ref="Value" minOccurs="1" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/GetMetadata.ashx?sessionToken=YOURSESSIONTOKEN &sourcePath=Folders/subfolder/myfile.txt
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?>
<Response>
<ResponseCode>0</ResponseCode>
<Metadata>
<Type>BitRate</Type>
<Value>4444</Value>
</Metadata>
</Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs GetMetadata.
SetMetadata
The SetMetadata method is used to set specified metadata for a file or folder.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to have the metadata set. | Required |
| metadata | The metadata to be set. The format is <type>:<value>. More than one metadata may be specified using multiple instances of this parameter. The maximum length for the metadata type is 100 characters. The maximum length for the metadata value is 400 characters. The metadata type and value must include characters that are compliant with XML formatted text. The following characters are not allowed in metadata: \ / : ? | * " < > | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the metadata set. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/SetMetadata.ashx?sessionToken=YOURSESSIONTOKEN &path=Folders/subfolder/myfile.txt&metadata=Title:MySong
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70019 | Metadata already exists | Occurs when the same metadata key is specified multiple times in a single call. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs SetMetadata.
DeleteAllTags
The DeleteAllTags method is used to remove all tags from a file or folder.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to have all tags removed. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the tag delete. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/DeleteAllTags.ashx?sessionToken=YOURSESSIONTOKEN &path=Folders/subfolder/myfile.txt
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs DeleteAllTags.
DeleteTags
The DeleteTags method is used to remove specified tags from a file or folder.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to have the specified tags removed. | Required |
| tag | The tags to be deleted. More than one tag may be specified using multiple instances of this parameter. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the tag delete. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/DeleteTags.ashx?sessionToken=YOURSESSIONTOKEN &path=Folders/subfolder/myfile.txt&tag=foo&tag=bar
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs DeleteTags.
GetTags
The GetTags method is used to retrieve all tags from a file or folder.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to have all tags retrieved. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the tag get. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element name="Tag" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/GetTags.ashx?sessionToken=YOURSESSIONTOKEN &path=Folders/subfolder/myfile.txt
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> <Tag>foo</Tag> <Tag>bar</Tag> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs GetTags.
SetTags
The SetTags method is used to set specified tags for a file or folder.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| path | The path to the file or folder to specify tags for. | Required |
| tag | The tags to be set. One or more tags may be specified using multiple instances of this parameter. This does allow for duplicate tags so if you specify multiple instances of the same tag, you will get all occurrences of that tag. The following characters are not allowed in a tag: * | | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the tag set. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Metadata/SetTags.ashx?sessionToken=YOURSESSIONTOKEN &path=Folders/subfolder/myfile.txt&tag=foo&tag=bar
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs SetTags.
SearchMetadata
The SearchMetadata method is used to search for items in your file system that match the specified metadata search criteria.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| username | The username of the account to be searched. | Required |
| searchKey | The metadata search key. Example: Duration. | Required |
| searchTerm | The search string to look for files and folders. The '*' character may be used at the beginning or end of the string to support wild card searches. Wildcards are not supported if the searchKey is MD5. | Required |
| maxResults | The maximum number of results to return | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the search. If the result is 0 the method was successful. | 0 |
| SearchCount | The number of results returned in the search. | 15 |
| CreatedDate | The date the file 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 |
REST XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="ResponseCode" minOccurs="1" type="xs:integer" />
<xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="SearchCount" minOccurs="1" type="xs:integer" />
<xs:element name="Item" minOccurs="0" maxOccurs="10000" >
<xs:complexType>
<xs:sequence>
<xs:element name="ItemPath" minOccurs="1" type="xs:string" />
<xs:element name="ItemName" minOccurs="1" type="xs:string" />
<xs:element name="CreatedDate" minOccurs="1" type="xs:string" />
<xs:element name="SizeBytes" minOccurs="1" type="xs:integer" />
<xs:element name="FileType" minOccurs="1" type="xs:string" />
<xs:element name="IsFile" minOccurs="1" type="xs:boolean" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/Metadata/SearchMetadata.ashx?sessionToken=YOURSESSIONTOKEN& username=myuser&searchKey=Duration&searchTerm=3*&maxResults=1000
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<ResponseCode>0</ResponseCode>
<SearchResults>
<SearchCount>1</SearchCount>
<Item>
<ItemPath>joebriggs.avi</ItemPath>
<ItemName>joebriggs.avi</ItemName>
<CreatedDate>Wed, 12 Sep 2007 11:06:46 GMT</CreatedDate>
<SizeBytes>7283012</SizeBytes>
<FileType>Video</FileType>
<IsFile>true</IsFile>
</Item>
</SearchResults>
</Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs SearchMetadata.
SearchTags
The SearchTags method is used to search for items in your file system that match the specified tag search criteria.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| username | The username of the account to be searched. | Required |
| searchTerm | The search string to look for in the tags. The '*' character may be used at the beginning or end of the string to support wild card searches. | Required |
| maxResults | The maximum number of results to return | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the search. If the result is 0 the method was successful. | 0 |
| SearchCount | The number of results returned in the search. | 15 |
| CreatedDate | The date the file 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 |
REST XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="ResponseCode" minOccurs="1" type="xs:integer" />
<xs:element name="ErrorMessage" minOccurs="0" type="xs:string" />
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element name="SearchCount" minOccurs="1" type="xs:integer" />
<xs:element name="Item" minOccurs="0" maxOccurs="10000" >
<xs:complexType>
<xs:sequence>
<xs:element name="ItemPath" minOccurs="1" type="xs:string" />
<xs:element name="ItemName" minOccurs="1" type="xs:string" />
<xs:element name="CreatedDate" minOccurs="1" type="xs:string" />
<xs:element name="SizeBytes" minOccurs="1" type="xs:integer" />
<xs:element name="FileType" minOccurs="1" type="xs:string" />
<xs:element name="IsFile" minOccurs="1" type="xs:boolean" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Sample REST Request
/ws/Metadata/SearchTags.ashx?sessionToken=YOURSESSIONTOKEN& username=myuser&searchTerm=mytag*&maxResults=1000
Sample REST XML Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<ResponseCode>0</ResponseCode>
<SearchResults>
<SearchCount>1</SearchCount>
<Item>
<ItemPath>joebriggs.avi</ItemPath>
<ItemName>joebriggs.avi</ItemName>
<CreatedDate>Wed, 12 Sep 2007 11:06:46 GMT</CreatedDate>
<SizeBytes>7283012</SizeBytes>
<FileType>Video</FileType>
<IsFile>true</IsFile>
</Item>
</SearchResults>
</Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs SearchTags.
Sharing Namespace
For Nirvanix Web Services 1.0 the sharing component only consists of hosting functionality. Host links are paths where everyone has read access. This could be used to host a website, share images, or other media, or to email links to files in a Nirvanix IFS account. A hosted link may be embedded into a webpage and presented as a standard ordinary web-hosted file. The return value would be the URL for the file or folder. The owner of the hosted item will always be the one charged for the download.
ListHostedItems
The ListHostedItems method is used to list all of the files and folders that the user has hosted.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| pageNumber | The page number to list. | Required |
| pageSize | The size of the page to return. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the copy. If the result is 0 the method was successful. | 0 |
| HostedItem | An object that describes the hosted items. |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element name="HostedItem">
<xs:complexType>
<xs:sequence>
<xs:element name="IsFile" type="xs:boolean" minOccurs="1"/>
<xs:element name="SharePath" type="xs:string" minOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Sharing/ListHostedItems.ashx?sessionToken=YOURSESSIONTOKEN &pageNumber=1&pageSize=10
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?>
<Response>
<ResponseCode>0</ResponseCode>
<HostedItem>
<IsFile>false</IsFile>
<SharePath>MyFolder/MySubfolder</SharePath>
</HostedItem>
<HostedItem>
<IsFile>true</IsFile>
<SharePath>MyFolder/MySharedFile.txt</SharePath>
</HostedItem>
</Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs 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 which includes any folders or files under it.
Please note that it may take up to 5 minutes for any file changes (e.g. move, rename and remove) to propagate after a hosted item is created.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| sharePath | The path to the file or folder to be hosted. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the copy. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
<xs:element name="DownloadLink" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Sharing/CreateHostedItem.ashx?sessionToken=YOURSESSIONTOKEN &sharePath=Folder/subfolder/samplefile.txt
Sample REST XML Response
<?xml version="1.0" encoding="UTF-8" ?> <Response> <ResponseCode>0</ResponseCode> <DownloadLink>http://mylinktodownloadthisfile.com</DownloadLink> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs CreateHostedItem.
RemoveHostedItem
The RemoveHostedItem method is used to remove the read access from everyone but the owner from a file or folder.
Please note that it may take up to 5 minutes for this method to take effect.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| sharePath | The path to the file or folder to be has its permissions restricted. | Required |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the copy. If the result is 0 the method was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Sharing/RemoveHostedItem.ashx?sessionToken=YOURSESSIONTOKEN &sharePath=Folder/subfolder/samplefile.txt
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs RemoveHostedItem.
Transfer Namespace
This namespace of the Nirvanix Web Services provides a set of API methods that allow a user to upload files to our Internet File System (IFS). An HTTP upload interface is also provided which is the preferred method of transport due to the overhead of SOAP.
AppendFile (SOAP ONLY)
The AppendFile method is used to upload a file in parts. If the path does not exist it will be created.
For example, if filename is "Vacations\2007\Hawaii\beachDay1.jpg" then when the file is done uploading the file would be added to Vacations\2007\Hawaii\beachDay1.jpg". The system creates all the folders that do not exist in this scenario.
With the HTTP Upload you can pass multiple files at once but for the AppendFile (SOAP) you can pass multiple files but only over multiple calls. A good example of using AppendFile to upload multiple files at once would be under a multithreaded application where each thread is uploading its own file. As long as each path being passed is different this will work correctly since we identify which file you are uploading by the path you pass.
Note: If you receive a transmission error or partial transmission you must call GetStorageNode to retrieve a new token and you must resend your file from byte 0.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| 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 |
| fileData | A byte[] array of the actual data to be sent. The maximum size of this array is 2,147,483,647 bytes. | Required |
| endOfFile | If this is the last part of the file to be uploaded this should be true, this will flag the file as finished and move it into the folder specified. Files being uploaded will not appear until this last part is specified and sent. | Required |
Output Values
None
Sample SOAP Request
Nirvanix.IMFS nirvFS = new Nirvanix.IMFS(); StorageNode node = nirvFS.GetStorageNode(sessionToken, 1024); Nirvanix.Transfer nirvTransfer = new Nirvanix.Transfer(); UriBuilder uriBuilder = new UriBuilder(nirvTransfer.Url); uriBuilder.Host = node.Host; nirvTransfer.Url = uriBuilder.ToString(); nirvTransfer.AppendFile(node.AccessToken, "Folder/mynewfile.jpg", fileData, false); nirvTransfer.AppendFile(node.AccessToken, "Folder/mynewfile.jpg", fileData, true);
Sample SOAP Response
Go to WSDL for AppendFile.
UploadFile (SOAP ONLY)
The UploadFile method is used to upload a file in its entirety. If the path does not exist it will be created. The maximum file size for uploading a file using this interface is 2 GB. If your file is larger than 2 GB, you must use the AppendFile method.
For example, if filename is "Vacations\2007\Hawaii\beachDay1.jpg" then when the file is done uploading the file would be added to "Vacations\2007\Hawaii\beachDay1.jpg". The system creates all the folders that do not exist in this scenario.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| 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 |
| fileData | A byte[] array of the actual data to be sent. The maximum size of this array is 2,147,483,647 bytes. | Required |
Output Values
None
Sample SOAP Request
Nirvanix.IMFS nirvFS = new Nirvanix.IMFS(); StorageNode node = nirvFS.GetStorageNode(sessionToken, 1024); Nirvanix.Transfer nirvTransfer = new Nirvanix.Transfer(); UriBuilder uriBuilder = new UriBuilder(nirvTransfer.Url); uriBuilder.Host = node.Host; nirvTransfer.Url = uriBuilder.ToString(); nirvTransfer.UploadFile(node.AccessToken, "Folder/mynewfile.jpg", fileData);
Sample SOAP Response
Go to WSDL for UploadFile.
HTTP Upload
Please refer to the Uploading Files section for extensive information on HTTP Upload.
back to topVideo 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 topPresetTranscode
The PresetTranscode method is used to convert a video file from one format to another.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFilePath | The video file to be transcoded. | Required |
| destFilePath | 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. | Required |
| callbackURL | The URL to be invoked when the transcode operation has been completed. | Optional |
| trackProgress | A flag to indicate whether the transcoding progress is available via metadata. If set to true, progress is available by retrieving the metadata on the source file being transcoded. Once the transcode is complete, this metadata is removed. The metadata is updated every 30 seconds. Defaults to false. Supported in REST only. | Optional |
| preset | Presets allow setting both the Codec and output format of the file as well as a quality level. The available presets are:
|
Required |
| options |
The available options are:
Note: The minimum height and width will vary depending on source file RESTEach option is passed as a separate parameter. Ex: &scaleWidth=640&scaleHeight=480
SOAPA string array of ':' delimited parameters. Ex: "scaleWidth:640". |
Optional |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the PresetTranscode command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual transcode operation was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Video/PresetTranscode.ashx?sessionToken=YOURSESSIONTOKEN& srcFilePath=myvideo.mpg&destFilePath=myvideo.flv&preset=H263+FLV+Medium&scaleWidth=640&scaleHeight=480
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
| 70126 | TranscodeException | This error will return the results of the transcoding operation if there is a failure. |
See code samples using our SDKs PresetTranscode.
Transcode
The Transcode method is used to convert a video file from one format to another.
Input Parameters
| Parameter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| srcFilePath | The video file to be transcoded. | Required |
| destFilePath | 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. | Required |
| callbackURL | The URL to be invoked when the transcode operation has been completed. | Optional |
| options |
The available options are:
Note: The minimum height and width will vary depending on source file RESTEach option is passed as a separate parameter. Ex: &numberOfFrames=10000&frameRate=24& width=640&height=480&aspectRatio=1.33&audioFreq=44100
SOAPA string array of ':' delimited parameters. Ex: "numberOfFrames:10000". |
Optional |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the transcode command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual transcode operation was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Video/Transcode.ashx?sessionToken=YOURSESSIONTOKEN &srcFilePath=myvideo.mpg&destFilePath=myvideo.flv&numberOfFrames=10000&frameRate=24&width=640&height=480&aspectRatio= 1.33&audioFreq=44100
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
| 70126 | TranscodeException | This error will return the results of the transcoding operation if there is a failure. |
See code samples using our SDKs Transcode.
ExtractFrames
The ExtractFrames method will extract frames from a video file and store them as images.
Input Parameters
| Parame.ter | Description | Required/Optional |
|---|---|---|
| sessionToken | A valid session token for the user. | Required |
| 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 when the frame extraction operation has been completed. | Optional |
| options | A list of ':' delimited optional parameters. The allowable parameters are:
The 'width' or 'height' may be set to -1 to maintain the aspect ratio of the video file frames, 'frameRate' is in frames per second. 'startTimeOffset' is the number of seconds to skip in the video prior to starting the frame extraction, 'frameName' is the name to be used for the images. Defaults to the name of the video file, 'frameFormat' is either 'jpg' (default), 'bmp', 'png', 'frameNumberDigits' is the number of digits to append to the 'frameName' when naming the extracted frame files. an example usage of these parameters on the REST call would be ...?width=100"frameName=goodframename"height=150"numberOfFrames=2 Note: If width is specified, height must be specified as well and vice versa. Note: The minimum height and width will vary depending on source file |
Optional |
Output Values
| Name | Description | Sample Value |
|---|---|---|
| ResponseCode | A result code with the status of the video frame extraction command. If the result is 0 the method was successful. However, you must wait until your callback URL was invoked (if specified) in order to determine if the actual video frame extraction operation was successful. | 0 |
REST XSD
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Response">
<xs:complexType>
<xs:sequence>
<xs:element ref="ResponseCode" minOccurs="1"/>
<xs:element ref="ErrorMessage" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ResponseCode">
<xs:simpleType>
<xs:restriction base="xs:integer" />
</xs:simpleType>
</xs:element>
<xs:element name="ErrorMessage" type="xs:string"/>
</xs:schema>
Sample REST Request
/ws/Video/ExtractFrames.ashx?sessionToken=YOURSESSIONTOKEN &srcFilePath=myvideo.mpg&destFolderPath=myFrameFolder&numberOfFrames=10000&frameName=MyFrame
Sample REST XML Response
<Response> <ResponseCode>0</ResponseCode> </Response>
Errors
| Code | Description | Details |
|---|---|---|
| 100 | Missing required parameters | Occurs when one or more required parameters is missing. |
| 70102 | Invalid path character | Occurs when any path contains illegal characters. |
| 80006 | Session not found | Occurs when the session cannot be found. This may happen after the session has been ended with an explicit log out or the session has expired due to inactivity. |
| 80101 | Invalid session token | Occurs when the session token is malformed. |
See code samples using our SDKs ExtractFrames.
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 topEvery web service method interacts with the Exception Framework to provide consistent, meaningful, non-technical responses to errors. If an exception is thrown, the outermost layer of the web service will catch the exception, and return two meaningful pieces: a Response Code and an Error Message.
Input Parameters
| Parameter | Description | Details |
|---|---|---|
| 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
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element ref="ResponseCode" />
<xs:element ref="ErrorMessage" />
</xs:schema>
Sample REST Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
<ResponseCode>80101</ responseCode>
<ErrorMessage>Invalid Session Token</errorMessage>
</response>
Sample SOAP Response
SOAP Header
Beginning of SOAP Body
<response ns="NirvanixException">
<responseCode>82005</ responseCode>
<errorMessage>Invalid Session Token</errorMessage>
</response>
End of SOAP Body
.Net SOAP Use for the Client
If the customer is developing their code in .Net, a SOAP Exception can be caught, and the error response retrieved from the Details property.
C# Example
accounting.CreateChildAccount() uses a Web Reference to make the SOAP call.
int responseCode = -1;
XmlNode xmlDetailNode;
int errorCode = 0;
int errorMessage = string.Empty;
try
{
responseCode = accounting.CreateChildAccount();
}
catch (SoapException ex)
{
xmlDetailNode = ex.Detail;
errorCode = int.Parse(
xmlDetailNode.SelectSingleNode("Response/ResponseCode").InnerText );
errorMessage = xmlDetailNode.SelectSingleNode("Response/ErrorMessage").InnerText;
}
If the Create Child Account SOAP call returns a Soap Exception, It will be caught, and the error response xml will be loaded into the xmlDetailNode. The values can then be read and loaded into the ResponseCode and ErrorMessage variables.
Errors
| Error Code | Type |
|---|---|
| 100 | MissingRequiredParameter |
| 101 | InvalidParameter |
| 160 | UnsupportedOperation |
| 50103 | ParameterOutOfAcceptedRange |
| 65003 | InvalidSlaError |
| 65004 | InvalidAppKey |
| 65005 | InvalidAccountType |
| 65006 | DuplicateUserNameUnderAppKey |
| 65007 | DuplicateAppName |
| 65008 | PageSizeExceedsLimit |
| 65009 | DeletedAccount |
| 65010 | InvalidStatus |
| 65012 | InvalidUserNameOrPassword |
| 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 |
| 70020 | CannotOverrideMetadata |
| 70026 | FileLocked |
| 70027 | FolderLocked |
| 70028 | FileFolderLockError |
| 70029 | FileFolderUnlockError |
| 70101 | NullOrEmptyPath |
| 70102 | InvalidPathCharacter |
| 70103 | InvalidAbsolutePath |
| 70104 | InvalidRelativePath |
| 70106 | FileIntegrityError |
| 70107 | InvalidMetadata |
| 70108 | RangeNotSatisfiable |
| 70109 | PathTooShort |
| 70110 | FileOffline |
| 70111 | InvalidImageDimensions |
| 70121 | InvalidUploadRequest |
| 70205 | NoRouteToSDN |
| 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 |
| 80104 | RestrictedIPAddress |
| 90001 | Configuration |
| 90002 | SSLRequired |
| 100001 | Unexpected error, please contact Nirvanix for more information. |
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 topCountry 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 | Aland 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 ofChina |
| 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 |
SOAP WSDL URLs
The namespaces below are groupings of methods for our SOAP Web Services and are not to be confused with a file system namespace, in which files can be grouped into folders, and folders can live inside other folders with other files (directory tree). Each of the namespaces below has a separate WSDL document describing those Web Services included in each namespace.
Authentication Namespace
http://services.nirvanix.com/ws/Authentication.asmx?WSDL
Account Management Namespace
http://services.nirvanix.com/ws/Accounting.asmx?WSDL
IMFS Namespace
http://services.nirvanix.com/ws/IMFS.asmx?WSDL
Metadata Namespace
http://services.nirvanix.com/ws/Metadata.asmx?WSDL
Sharing Namespace
http://services.nirvanix.com/ws/Sharing.asmx?WSDL
Image Namespace
http://services.nirvanix.com/ws/Image.asmx?WSDL
Transfer Namespace
http://node1.nirvanix.com/ws/Transfer.asmx?WSDL
Audio Namespace
http://services.nirvanix.com/ws/Audio.asmx?WSDL
Video Namespace
http://services.nirvanix.com/ws/Video.asmx?WSDL
Image Conversion Formats
The Image Resize method allows creating new files from an existing image file. Below are the formats that are allowed in this method.
| Format | Input | Output |
|---|---|---|
| Bitmap (Windows, RLE, OS/2) | X | X |
| Exif | X | X |
| Emf | X | X |
| Gif | X | X |
| Ico | X | X |
| Jpg | X | X |
| Png | X | X |
| Tiff | X | X |
| Wmv | X | X |
Audio Transcode Formats / Codecs
The list below is broken into format and codec since the file format may not always dictate the codec being used for that file.
Audio Formats (Does not include codecs)
| Format | Input | Output |
|---|---|---|
| AAC | X | X |
| AC3 / DTS | X | X |
| AC3ACM | X | X |
| FLAC | X | X |
| LPCM /MP1 / MP2 | X | X |
| MP3 | X | X |
| Vorbis | X | X |
| Wave | X | X |
Audio Codecs (Independent of file format)
| Codec | Input | Output |
|---|---|---|
| ATSC A/52 / AC-3 (.ac3) | X | |
| Various ADPCM | X | X |
| ALAC (Apple Lossless Audio Codec) (.alac) | X | |
| DCA (DTS Coherent Acoustics) | X | |
| Delphine Software International CIN audio | X | |
| FLAC (Free Lossless Audio Codec) (.flac) | X | X |
| IMC (Intel Music Coder) | X | |
| Meridian Lossless Packing | X | |
| MP2 (MPEG audio layer 2) (.mp2) | X | X |
| MP3 (MPEG audio layer 3) (.mp3) | X | X |
| Various PCM Formats | X | X |
| RealAudio 1.0 / 2.0 | X | |
| Vorbis (.vorbis) | X | X |
| Windows Media Audio 1 / 2 (.wmav1, .wmav2) | X | X |
Video PresetTranscode Formats / Codecs
The list below is broken into format and codec since the file format may not always dictate the codec being used for that file. A separate list of audio codecs handled is also given for our video processor.
Video Formats (Does not include codecs)
| Format | Input | Output |
|---|---|---|
| FLV | X | |
| AVI | X | |
| MPG, MP1, MP2, MP4, Mpeg | X | (MP4 support being considered for a future release) |
| MOV | X | |
| WMV | X | |
| DIVX | X | |
| FLAC | X |
Video Codecs (Independent of file format)
| Codec | Input | Output |
|---|---|---|
| H263 | X | X |
| H264 | X | X |
| XVID | X | |
| DIVX | X | |
| On2 VP6 | X | |
| On2 VP7 | X | |
| MPEG-2 (Cyberlink) | X | |
| MPEG-2 (Gabest) | X | |
| MPEG-1 (MainConcept) | X | |
| Intel Indeo 4 | X | |
| Intel Indeo 5 | X | |
| Intel I.263 | X | |
| huffyuv | X | |
| YV12 | X | |
| InterVideo | X | |
| Ligos | X | |
| Windows Media Video 7,8,9 | X |
Video PresetTranscode Audio Codecs (Independent of file format)
| Codec | Input | Output |
|---|---|---|
| AC3 / DTS | X | X |
| Vorbis | X | X |
| AAC | X | X |
| FLAC | X | X |
| LPCM /MP1 / MP2 | X | X |
| MP3 (Fraunhofer) | X | X |
| MP3 (LAME) | X | X |
| AC3ACM | X | X |
| DivX Audio | X | X |