Skip to end of metadata
Go to start of metadata

IMS v6 provides a SOAP interface, designed for folder browsing and file uploads. The following notes provide an introduction to using the API.

Note that the SOAP API uses the term "album" in method names and request & response parameters. This is for historic reasons, and in client user interfaces the term "folder" should be used instead.

SOAP is not the primary API for IMS. For most purposes, please use the JSON API.

Overview

The SOAP server URL is found here:

<IMS Site URL>/soap/soap_server_uploadtool.tlxr

You must also specify a client service version with a GET variable named client. Currently the latest service version is "1.1" and this should be specified in requests to the server. However, the client should support the ability to change the requested service version after issuing the CheckVersion() call described below. This allows the server to indicate to the client that there is a more recent, compatible service version available.

e.g.
http://mysite.thirdlight.com/soap/soap_server_uploadtool.tlx?client=1.1

The SOAP WSDL file location is:

<IMS Site URL>/soap/soap_wsdl_uploadtool.tlx

e.g.
http://mysite.thirdlight.com/soap/soap_wsdl_uploadtool.tlx

You should query the WSDL for the definitive list of available methods, and request & response variable types required for each. Further discussion of SOAP protocol usage and implementation are outside the scope of this document, however, there is a wealth of information available on the internet.

Error Handling

All responses from the SOAP server contain two result codes as well as any data relevant to the request. These result codes are the APIResult and ActionResult. It is important to check these codes after each request in order to trap errors and explain to the user if something went wrong.

API result codes indicate a problem, if any, with the SOAP Server environment. If there is such a problem (i.e. APIResult != "OK") then ActionResult will always be "API_ERROR". Otherwise, action result codes indicate a problem specifically related to the requested action, e.g. "OVER_QUOTA" may be returned if a site does not have enough disk space for a particular file upload. Normally both ActionResult and APIResult are both equal to "OK".

Both result code types are fully specified in the WSDL and should be self-explanatory.

Checking the Client and Service Version

The first method call to the API must always be a CheckVersion() call. This allows the server to indicate service compatibility or otherwise to the client. It also responds with a preferred service version.

The request to CheckVersion() should contain a single version string. This has a particular format as follows:

<Service Version * 10>.<Platform String>.<Client version as dot separated numeric>

(Service Version * 10 means "multiply the service version by ten")

e.g.:

"11.IOS.1.0"
"10.WIN.5.9.26"
"11.MAC.1.8"

Notes:

  • The service version will always have only one decimal place. Multiplying by 10 will always yield an integer.
  • The platform strings are as follows:
    "MAC" - Mac Cocoa build
    "WIN" - Windows .NET build
    "IOS" - iPhone/iPad app
  • The client version string is particular to the client app, but must be numerical, separated by dots.

In the response to CheckVersion there is a m_strServiceVersion value. This should be used as the client service version in all further calls to the SOAP server.

e.g.

{{http://mysite.thirdlight.com/soap/soap_wsdl_uploadtool.tlx?client=_Value_of_m_strServiceVersion_}}

The response contains these variables:

m_strLatestVersion - this is the latest client version known to the server
m_bRunningLatestVersion - a boolean indicating whether the current client is running the latest known client version
m_bVersionIsCompatible - a boolean indicating whether the current client is compatible with the server (i.e. whether you can continue without upgrading)
m_strURLForLatestVersion - a url to visit to find details and a download link for the latest client version
m_strServiceVersion - this is the server version to use from now on - i.e. in the "client" GET variable. It will be compatible with that initially requested.

Examples:

CheckVersion("11.IOS.1.0")
Response:
{
    m_strLatestVersion  = "1.0"
    m_bRunningLatestVersion = true
    m_bVersionIsCompatible = true
    m_strURLForLatestVersion = ""
    m_strServiceVersion = "1.1"
}

CheckVersion("11.MAC.1.7")
Response:
{
    m_strLatestVersion  = "1.8"
    m_bRunningLatestVersion = false
    m_bVersionIsCompatible = false
    m_strURLForLatestVersion = "http://www.thirdlight.com/ims/features/uploader"
    m_strServiceVersion = "1.1"
}

The m_bVersionIsCompatible boolean must be checked. If this is false then the application should not continue.

The Login Call

The Login() call requires a username and password. These are the same as the the user's normal IMS web login username and password. Within the response from the Login() call there will be an objUserPermissions structure that contains a number of booleans indicating available permissions for this user. It is important to use this structure to determine what actions a user can perform, and thus adjust the interface accordingly. Please refer to the WSDL for a definition of objUserPermissions.

Cookies

Along with the normal SOAP response from the Login request, a cookie will be set in the HTTP headers. You must use this cookie in all further communication in order to stay logged in. Send this cookie back in the normal way using HTTP request headers.

Performing Actions

There are various methods in the API that may be of use. Highlighted below are those most useful for browsing the folder structure and uploading files.

GetTopLevelAlbums()

Returns a list of available top level folders, with pertinent details including Folder ID, (m_nAlbumID), Folder name (m_strName) and whether there are sub-folders (m_bHasChildren).

GetAlbumsByParentAlbumID()

Returns sub-folders in a similar structure to above for a particular parent folder. Specfiy the folder using the m_nAlbumID value provided in the folder details structure returned from the GetTopLevelAlbums() call.

This method can be used recursively to iterate over the entire folder structure visible to the user.

GetAssetsByAlbumID()

Returns a list of details for all files within particular folder. This can be used if you want to list the files within folders.

Uploading

File uploads are not peformed over the SOAP protocol owing to issues we have found sending large amounts of binary information using SOAP. Instead file upload is performed over a normal POST request, in the same manner a web form would POST a file using a multipart/form-data encoding type.

File uploads should be posted to the following URL:
<IMS Site URL>/soapfileupload.tlxr

The client service version and folder ID must be specified in GET parameters as in the following example:
e.g.

http://mysite.thirdlight.com/soapfileupload.tlxr?client=1.1&album=_Folder_ID_

The uploaded file data should have the name "file". This mimics a web form with the following structure:

<form
    enctype="multipart/form-data" 
    action="http://mysite.thirdlight.com/soapfileupload.tlxr?client=1.1&album=_Folder_ID_" 
    method="POST">
    <input name="file" type="file" />
</form>

The cookie obtained after the Login() call must be sent along with the HTTP headers as with all other communication with the SOAP server.

Following upload, the server will respond with a snippet of XML as follows:

<thirdlight>
    <upload-result  apiresult="OK" 
                    actionresult="OK"
                    assetid="[New file's ID]"
                    assettype="[New file's asset type]"
                    albumid="[New file's folder ID]"
                    filename="[New file's filename]"
                    filesize="[New file's filesize]"
                    pending="[boolean - whether the file has entered an approvals workflow]"
                    />
</thirdlight>

Third Light IMS also has other APIs which provide greater functionality than SOAP.

  • No labels