Difference between revisions of "REST API:login Resource"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
m (Text replace - '[[Role Based Access' to '[[Data Access')
Line 3: Line 3:
===Requirements===
===Requirements===
:*[[User]] must have a valid account on the {{enterprisebrand}}
:*[[User]] must have a valid account on the {{enterprisebrand}}
:*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 [[Role Based Access Permissions]] granted to the User.
:*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===
===Logging In===

Revision as of 01:39, 16 October 2012

Performs a Login action via the REST API

Requirements

  • User must have a valid account on the AgileApps Cloud 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://{yourDomain}/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;

// Apache Utilities
import org.apache.commons.lang.StringUtils;  

// Java Utilities
import java.util.List;
import java.io.InputStream;
import javax.ws.rs.core.MultivaluedMap; 

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

      // Combine cookie parameters from the response header,
      // making a cookie string for use in subsequent requests.
      MultivaluedMap<String,String> headers = response.getHeaders();  
      String cookieString = "";
      List<String> cookieParams = headers.get("Set-Cookie");
      cookieString = StringUtils.join(cookieParams, "; ");

      return cookieString;
    }
    catch (Exception e)
    {
      e.printStackTrace();
    }
    return null;
  }

  // ...Various utility methods...

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