Third Light Developer Exchange

steve

Third Light Staff

Registered: 2013-06-06

Posts: 105

First steps with the API

The quickest way to make a test of an API call is by crafting a simple GET request.

The example below shows how a session ID can be obtained by making a request that uses an API key for authentication.

1) The API key first needs to be created from this page in the IMS administration console:

Configuration > Site Options > IMS API

2) Now manually craft a URL like this substituting your API key:

http://yoursite.com/api.json.tlx?json={"inParams":{"apikey":"IJPtL39u8vMfntBgVm7bvGDGUXRRu8FC"},"action":"Core.LoginWithKey","apiVersion":"1.0"}

(for readability, no escaping has been applied but you will need to consider this should your API key contain special characters).

The output returned should match this format:

{"result":{"api":"OK","action":"OK"},"outParams":{"sessionId":" xjHb3VV76D,fsXqG54FZzB8iZu-XRFHG"}}

Making a request

The request data must be JSON encoded and can be included in the request in a number of ways:

• GET request using a json GET parameter

• POST request with the post body encoded as 'application/x-www-form-urlencoded'. The server will look for a json parameter in the POST data

• POST request with raw JSON contained in the POST body

The JSON encoded request data must contain an action and apiVersion key but can also contain a number of extra keys:

• action (required) - the name of the API method

• apiVersion (required) - the API version to use (only option is "1.0" at present)

• inParams - a hash of any relevant input parameters

• sessionId - optional session key, used to keep track of an authenticated user

• callback - enables JSONP usage; the name of the callback function to use

Receiving a response
The response to an API request will be JSON encoded, and contain the following keys:

• result - information about the result

• api - an API Result Code indicating success or otherwise of the API framework

• action - an Action Result Code indicating the success or otherwise of the particular method call

• cache - an optional hash of caching information

• nocache - boolean indicating if this response should not be cached

• debug - if debugging is enabled, this may contain a string with relevant debug information

• outParams - if applicable, the data returned by the method call

The content-type of the response will be "application/json" unless a JSONP callback has been specified - in which case the callback is used and the response's content-type will be "text/javascript".

Sessions
A user should be authenticated using the Core.Login method which returns a session identifier. This identifier must be sent with any further commands in order to stay logged in as the user. The session ID can be sent in two ways:

1. Using the sessionId parameter as described above

2. Using an HTTP cookie with the name "PHPSESSID"

Last edited by steve (2013-06-12 16:40:50)

steve

Third Light Staff

Registered: 2013-06-06

Posts: 105

Re: First steps with the API

Examples

The following examples demonstrate the various ways of communicating with the API. For clarity, only relevant HTTP headers are shown, URL encoding has been ignored, and line wraps have been added to long JSON strings. These are otherwise valid HTTP transactions.

Using GET
Requesting the number of files in the library using Core.GetFileCount which returns a simple integer. This also demonstrates that the session key can be included as a conventional cookie with name "PHPSESSID". This is an alternative to using the sessionId key described above.

// Request
GET /api.json.tlx?json={"apiVersion":"1.0","action":"Core.GetFileCount"} HTTP/1.0
Host: ims.mycompany.com
Cookie: PHPSESSID=64066969613f669922bfc63fee71d68f;
 
// Response
HTTP/1.0 200 OK
Content-Type: application/json
 
{"result":{"api":"OK","action":"OK"},"outParams":13767}

Using POST

This demonstrates using POST with a form-urlencoded body. It uses Folders.CreateFolder to create a new folder in the IMS library. The method returns some pertinent details about the new folder. Note this also demonstrates use of the JSONP callback.

// Request
POST /api.json.tlx HTTP/1.0
Host: ims.mycompany.com
Content-Type: application/x-www-form-urlencoded
 
json={"apiVersion":"1.0",
      "sessionId":"64066969613f669922bfc63fee71d68f",
      "action":"Folders.CreateFolder",
      "inParams":{
          "type":4,
          "folderName":"Panoramic Photos"
      },
      "callback":"handleResponse"}
 
// Response
HTTP/1.0 200 OK
Content-Type: text/javascript
 
handleResponse({
    "result":{
        "api":"OK",
        "action":"OK"
    },
    "outParams":{
        "id":"9313801987",
        "name":"Panoramic Photos",
        "hasChildContainers":false,
        "hasChildAssets":false
    }
})

Using a raw POST body

// Request
POST /api.json.tlx HTTP/1.0
Host: ims.mycompany.com
Content-Type: application/json
 
{"apiVersion":"1.0",
 "action":"Files.Delete",
 "inParams":{
     "assetId":873234221
 }
}
 
// Response
HTTP/1.0 200 OK
Content-Type: text/javascript
 
{"result":{"api":"OK","action":"ACTION_NOT_PERMITTED","debug":""}}