LongJump Support Wiki

REST API:Session Management Resources

From LongJump Support Wiki
Revision as of 22:14, 4 October 2010 by imported>Aeric (→‎Logged in User Info)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Manage a session using the REST API

Login

Performs a Login action via the REST API

Requirements

  • User must have a valid account on the LongJump Platform
  • All subsequent REST API calls execute within the context of the User that is logged in. As with all UI actions, this means that any subsequent REST API calls (to access levels, data visibility, team membership, etc.), are governed by the Data Access Permissions granted to the User.

Logging In

Method
POST
URI
https://na.longjump.com/networking/rest/login
Request
<platform>
   <login>
       <userName>jim@acme.com</userName>
       <password>jimacme</password>
   </login>
</platform>
Response
Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.
<platform>
  <login>
     <userId>qwe123rty456</userId>
     <email>jim@acme.com</email>
     <userName>jim@acme.com</userName>
     <firstName>Jim</firstName>
     <lastName>Acme</lastName>
     <organizationName>Acme Inc.</organizationName>
     <organizationId>473474</organizationId>
     <timeZone>12</timeZone>
     <primaryTeamId>1</primaryTeamId>
     <employeeNumber></employeeNumber>
     <sessionId>xyz789uio987</sessionId>
     <startingAppId type="" 
        uri="https://{domain}/networking/rest/application/446yyt677wwz"
        displayValue="">446yyt677wwz</startingAppId>
     <userLocale>en</userLocale>
     <userDateFormat>MM/dd/yyyy</userDateFormat>
  </login>

  <message>
     <code>0</code>
     <description>Success</description>
  </message>
</platform>
See also: REST API:Error Codes
Fields

These fields are required when logging in:

Name Type Description
userName String User's login name
password String User's login password

Sample Login Client

This code from the BaseClient sample program uses the Apache wink RestClient to make a REST login request and get a sessionId. It uses the Apache Wink client to post the login request, and calls a utility method defined in the BaseUtil] class to extract the sessionId from the response.
package demo.rest;

//HTTP Classes
import org.apache.wink.client.RestClient;
import org.apache.wink.client.Resource;
import org.apache.wink.client.ClientResponse;
import org.apache.commons.httpclient.HttpStatus;

// Utility Classes
import java.io.InputStream;

/*
 * A base client that handles login and logout and provides utility
 * methods for programs that use REST APIs.
 * 
 * Note:
 * This class uses the Apache wink RestClient, which makes it
 * pretty easy to make requests and handle responses. 
 */
public class BaseClient {
  
  String sessionId;
  RestClient client;
  
  String baseUrl = "https://{domain}";
  String username = "yourName";
  String password = "yourPassword";
  
  public String login()
  { 
    String url = baseUrl + "/networking/rest/login";
    String xml = "<platform>"
        + "<login>"
            + "<userName>"+username+"</userName>"
            + "<password>"+password+"</password>"
        + "</login>"
        + "</platform>";
    try
    {
      System.out.println("Logging in");
      this.client = new RestClient();
      Resource resource = client.resource(url);
      resource.contentType("application/xml");
      resource.accept("application/xml");
      ClientResponse response = resource.post(xml);
      String responseXml = response.getEntity(String.class);    
      this.sessionId = getValue("/platform/login/sessionId", responseXml);
      return this.sessionId;
    }
    catch (Exception e)
    {
      e.printStackTrace();
    }
    return null;
  }

  /*
   * Get a value from XML returned in a response.
   * 
   * @param xpath_expr  An XPATH expression. 
   *                    For example: "/platform/login/sessionId"
   *                    
   * @param xml The XML string to be parsed. Generally obtained using
   *        ClientResponse.getEntity(String.class) --Apache wink RestClient
   *        httpMethod.getResponseBodyAsString()   --Apache HttpClient
   */
  public static String getValue(String xpath_expr, String xml) 
  { 
    return BaseUtil.xpath_result(xpath_expr, xml);
  }

  // ...Other utility methods used by subclasses...

  public static void main(String args[])
  {
    BaseClient client = new BaseClient();
    String sessionId = client.login();
    System.out.println("SessionId is: " + sessionId);
    client.logout();
  }

Logging In as Customer Support

Login to a client tenancy as the "Customer Support" user, with system admin privileges.

Method
POST
URI
https://na.longjump.com/networking/rest/login/customerSupport
Request
<platform>
   <login>
       <userName>Adrian@AceAdmin.com</userName>
       <password>AdrianAdmin</password>
       <client_tenant_id>464938724568972</client_tenant_id>
   </login>
</platform>
Response
Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.
Fields

These fields are required:

  • userName - Tenant admin's login name
  • password - Tenant admin's password
  • client_tenant_id - ID of the tenant to log into

Doing a Proxy Login

Permissions permitting, login to a client tenancy as a user in that tenancy, in order to review and/or fix the environment in which the customer is having problems.

Method
POST
URI
https://na.longjump.com/networking/rest/login/proxyLogin
Request
<platform>
   <login>
       <userName>Adrian@AceAdmin.com</userName>
       <password>AdrianAdmin</password>
       <proxy_user_id>464938724568972</proxy_user_id>
   </login>
</platform>
Response
Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.
Fields

These fields are required:

  • userName - Tenant admin's login name
  • password - Tenant admin's password
  • proxy_user_id - ID of the user the admin will "become", for the duration of session

Switching Back to Your Original Session

This resource restores your original session, after having logged in to another tenancy using proxyLogin, so you don't have to log out of the customer's tenancy and then log in all over again. (It can be used in a REST client, or simply pasted into your browser to restore your previous session.)

Method
GET
URI
https://na.longjump.com/networking/rest/login/proxyLogin/switchBack
Response
Session identifier required for succeeding REST calls, along with user details such as first name, last name, and employee number.


Logout

Performs a Logout action via the REST API

Method
GET
URI
https://na.longjump.com/networking/rest/logout
Response
<platform>
    <message>
	<code>0</code>
	<description>Success</description>		
    </message>
</platform>
Sample Logout Code

This code taken from the BaseClient sample shows how to make a REST logout request. (It ignores HTTP return codes, because the goal is to log out, and pretty much the only way to get an error would be if the session had already terminated.) 

  public void logout()
  {
    System.out.println("Logging out");
    String url = baseUrl + "/networking/rest/logout";
    Resource logoutResource = this.client.resource(url);
    logoutResource.accept("application/xml").get();
  }


Is a Valid Session in Progress?

Determine if the current session is valid.

Method
GET
URI
https://na.longjump.com/networking/rest/user/isSessionValid
Response
:
<platform>
    <user>
        <is_session_valid>true</is_session_valid>
    </user>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
See also: REST API:Error Codes

Logged in User Info

Gets information about the logged in user.

Method
GET
URI
https://na.longjump.com/networking/rest/user/info
Response
The same information returned by the query to Get a User Record: first name, last name, employee number, and so on.
Retrieved from "https://agileappscloud.info/ljwiki-src/index.php?title=REST_API:Session_Management_Resources&oldid=8669"