Home › Blogs › ilo's blog

SugarCRM: REST call example

Wed, 09/02/2009 - 02:13 — ilo

SugarCRM includes the RESTful services in the 5.5 version. The API set is quite similar to the SOAP implementation, but somethings are missing right now. The documentation is still in DRAFT state, and the services also has some issues to be resolved. This is one of the reason why I decided to join the SugarCRM TestFest. In any case, this will be a short introduction about RESTful services and how to call them. Please, note that these are results from SugarCRM 5.5.Beta1.

The first implementation I've seen comes with the SugarCRM 5.5.Beta1 package, in javascript format in the file service/example.html. I've tried with Firefox and IE, but didn't work.. The next search landed me to this post in the SugarCRM forums, where I found this example (sligthly modified for better understanding):

<?php
  $req =& new HTTP_Request($url);
  $req->setMethod(HTTP_REQUEST_METHOD_POST);
  $json = getJSONobj();
  $auth = array(
      'user_name' => $user_name,
      'password'   => md5($user_password),
      'version'=>'.01',
  );
  $jsonEncodedData = $json->encode( array( 'user_auth' => $auth, 'application_name'=>'TRIPInfo', 'name_value_list' => array() ), FALSE);

  $req->addPostData('method', 'login');
  $req->addPostData('input_type', 'json');
  $req->addPostData('response_type', 'json');
  $req->addPostData('rest_data', $jsonEncodedData);

  $req->sendRequest();
  $list = $req->getResponseBody();
?>

First, it's important to notice that version 2 of WebServices API now includes more parameters in the login method, the name_value_list, that could be used to let SugarCRM know the language or subscription options for the user calling the operation.

So, for the login method, the parameter list is now (as described in the the SugarCRM wiki - 5.5 WebServices Overview Draft 2:

.. In version 2 we have rewritten all of the API calls. ..

But in that document, the argument list of the login API states:

Syntax
login($user_auth, $application)

The next move is to find an updated version. This SugarCRM forum thread includes a Sugar_5.5_WebServices_API_Guide_DRAFT.pdf.zip, where you could find an updated definition of the API parameters:

user_auth Array: Sets username and password
application String: Not used. The name of the application from which the user is loggin in.
name_value_list Array: Sets the name_value pair. Currently you can use this function to set values for the ‘language’ and ‘notifyonsave’ parameters.

The bad part of this document is that it does not include anything about the expected reply.. ok.. let's move on.. The "Login Brief":

So we want to do a login using RESTful services, we have to set this ammount of parameters:

  • 'method': string
  • 'input_type': string
  • 'response_type': string
  • 'rest_data': encoded API parameters:
    • 'user_auth': array,
      • user_name: string,
      • password: md5 of string,
      • version: string,
    • 'application': string,
    • 'name_value_list': array

I just said encoded, because you can use both 'json' or 'serialize' encoding for your requests, considering that you can also mix input and output types for the requests. Let's convert this to curl, to get new code working:

<?php
// You should put your own values here..
$user_name = 'theusernameyouwant';
$password  = 'thepassword for the user';
$url = 'http://localhost/sugardev/service/v2/rest.php';

//Perform a post request to the REST interface..
function do_post_request($url, $params) {
  $options = array(
    CURLOPT_RETURNTRANSFER => TRUE,     // return web page
    CURLOPT_HEADER => FALSE,     // don't return headers
    CURLOPT_POST => TRUE,     // Set a post request
    CURLOPT_POSTFIELDS => $params,
    CURLOPT_FOLLOWLOCATION => TRUE,     // follow redirects
  );
  $ch = curl_init( $url );
  curl_setopt_array( $ch, $options );
  $content = curl_exec( $ch );
  return $content;
}

//The language to interact with RESTful service is json content
function json_rest_request($url, $api_params) {
  $params = array(
    'method' => 'login',
    'input_type' => 'json',
    'response_type' => 'json',
    'rest_data' => json_encode($api_params),
  );
  $result = do_post_request($url, $params);
  // response is in json, so decode..
  return json_decode($result);
}

//The language to interact with RESTful service is serialized content
function serialize_rest_request($url, $api_params) {
  $params = array(
    'method' => 'login',
    'input_type' => 'serialize',
    'response_type' => 'serialize',
    'rest_data' => serialize($api_params),
  );
  $result = do_post_request($url, $params);
  // response is serialized, so decode..
  return unserialize($result);
}

//The language to interact with RESTful service is json, but should answer serialized content
function mixed_rest_request($url, $api_params) {
  $params = array(
    'method' => 'login',
    'input_type' => 'json',
    'response_type' => 'serialize',
    'rest_data' => json_encode($api_params),
  );
  $result = do_post_request($url, $params);
  // response is serialize, so decode..
  return unserialize($result);
}


//Now call the RESTful service
$api_params = array(
  'user_auth'=>  array(
      'user_name'=> $user_name,
        'password' =>md5($password),
        'version'=>'.01',
    ),
    'application_name'=>'SugarOnDrupal',
    'name_value_list' => array(),
);

print "<pre>";
print "Should return an stdClass\n";
print_r(json_rest_request($url, $api_params));
print "Should return an array\n";
print_r(serialize_rest_request($url, $api_params));
print "Should return an array\n";
print_r(mixed_rest_request($url, $api_params));
print "</pre>";
?>

Ok, if we try the example we could see what that json_rest_request call gets as result:

Should return an stdClass
stdClass Object
(
    [id] => dc13b5aa409dd1919b834f7c2265aaef
    [module_name] => Users
    [name_value_list] => Array
        (
            [0] => 1
            [1] => admin
            [2] => en_us
        )

)

We would also notice that serialize_rest_request request returns empty content, and mixed_rest_request returns an array. But the MOST important thing to consider is that there's no complex-type:error in the return as specified in SugarCRM wiki:

error_value is a struct containing three parameters:
string:number - this is the error number. An error number of 0 indicates no errors were encountered
string:name – this is the error name
string:description – this is the error description

Now, I want you to welcome back to reality, this is SugarCRM 5.5.Beta1. For the testFest we will work in making all these issues just dust in the wind, doing things as they should, and building a better documentation. I would like to quote Wichard again: No point in complaining about QA afterward if you don't make an effort in participating upfront.

AttachmentSize
test_sugarcrm_v2_rest.php.txt2.34 KB