1 de 7
http://www.ibm.com/developerworks/library/x-sugarcrmrest/#l3
developerWorks
Technical topics
XML
Technical library
Share:
John Mertic is a software engineer at SugarCRM, and has several years of experience with PHP Web applications. At SugarCRM, he has
specialized in data integration, mobile and user interface architecture. An avid writer, he has been published in php|architect, IBM
developerWorks, and in the Apple Developer Connector, and is the author of the book 'The Definitive Guide to SugarCRM: Better Business
Applications'. He has also contributed to many open source projects, most notably the PHP project where he is the creator and maintainer of
the PHP Windows Installer. He can be reached at jmertic@gmail.com.
02 Feb 2010 - Added Resource item for 02 Feb 2010 article about
SugarCRM connectors by the author.
What is REST?
REST, which stands for REpresentational State Transfer, is designed to be a
very mean, lean Web services protocol. It came into being as a response to
heavyweight Web services protocols such as SOAP and XML-RPC, which
rely on a predefined messaging format and methods to pass them
back and forth between servers and clients. REST, on the other
hand, specifies no such limitations; you can use any message
format that you like (whether it be JSON, XML, HTML, serialized
data, or even straight text), and operates on the standard HTTP
verbs of GET, DELETE, and POST for its operations. The rules that
exist for REST client/server interactions can be completely defined
by the application requirements. So if you define a REST interface
Each REST Web services call is just a simple HTTP request, using one of the standard HTTP verbs.
Typically, you'll use the verb most appropriate for the action you are performing:
GET to retrieve data from a server
POST to send data from a server
DELETE to delete a resource on a server
Listing 1 shows how an example interaction with the Yahoo! search REST Web service with PHP works
06/08/2015 20:03
2 de 7
http://www.ibm.com/developerworks/library/x-sugarcrmrest/#l3
(see Downloads to have all of the examples in this article at your fingertips).
Listing 1. Example of interacting with a REST Web service in PHP
<?php
// specify the REST web service to interact with
$url = 'http://search.yahooapis.com/WebSearchService/V1/
webSearch?appid=YahooDemo&query=sugarcrm';
// make the web services call; the results are returned in XML format
$resultsXml = file_get_contents($url);
// convert XML to a SimpleXML object
$xmlObject = simplexml_load_string($resultsXml);
// iterate over the object to get the title of each search result
foreach ( $xmlObject->Result as $result )
echo "{$result->Title}\n";
For this example in Listing 1, you are doing a search for sugarcrm using the Yahoo Web Search Service.
You use the PHP function file_get_contents(), which performs a GET request using the URL
specified. By default it returns the results of the query as an XML string, and the PHP SimpleXML library
is used to parse it into a PHP object you can iterate over to get the desired data you are looking for.
Now that you understand how REST Web services work, see how you can interact with SugarCRM using
their Web services interface.
Since you need to make a POST request to the Web service instead of a GET request, use the PHP curl
library instead of file_get_contents() to make the call to the Sugar Web service. You then assemble
the parameters for the Web services call as an array, which you encode as a JSON string. You specify
the parameters for this Web service call, the method (which is login for this call), and the format you are
using to pass the parameters to the service using the input_type POST parameter (which can be one
of json or serialized). You also must specify the format you expect the results to be returned as for
the response_type parameter (which can be one of json, rss, or serialized), and then specify the
JSON encoded parameters string for the Web service method as rest_data. You then make the actual
call, and decode the returned JSON string passed from the server. The main return value you are
concerned with for this request is the id parameter, which is used as a parameter in subsequent
requests to identify to the server that you have already authenticated to the service.
06/08/2015 20:03
3 de 7
http://www.ibm.com/developerworks/library/x-sugarcrmrest/#l3
In Listing 3, you'll see how you can add a new record to the Accounts module using the interface.
Listing 3. Adding a new Account using the REST Web services interface
<?php
// specify the REST web service to interact with
$url = 'http://localhost/sugar/v2/rest.php';
// Open a curl session for making the call
$curl = curl_init($url);
// Tell curl to use HTTP POST
curl_setopt($curl, CURLOPT_POST, true);
// Tell curl not to return headers, but do return the response
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the POST arguments to pass to the Sugar server
$parameters = array(
'user_name' => 'user',
'password' => 'password',
);
$json = json_encode($parameters);
$postArgs = 'method=login&input_type=json&
response_type=json&rest_data=' . $json;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Close the connection
curl_close($session);
// Convert the result from JSON format to a PHP array
$result = json_decode($response);
// Get the session id
$sessionId = $result['id'];
// Now, let's add a new Accounts record
$parameters = array(
'session' => $session,
'module' => 'Accounts',
'name_value_list' => array(
array('name' => 'name', 'value' => 'New Account'),
array('name' => 'description', 'value' => 'This is an
account created from a REST web services call'),
),
);
$json = json_encode($parameters);
$postArgs = 'method=set_entry&input_type=json&
response_type=json&rest_data=' . $json;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = json_decode($response);
// Get the newly created record id
$recordId = $result['id'];
After logging into the Web service, you make a second Web services call, this time to the set_entry
Web service method. You specify the session id that was returned by the login method as the session
parameter, and the module you are adding the record into as the module parameter. The
name_value_list parameter is a name/value pair list of the field values you wish to set for the newly
created record. You then make the Web services call, which returns the record id of the newly created
record.
You can also update a record by calling the same set_entry method once again, being sure to pass the
record id you want to update in the name_value_pair list, as in Listing 4.
Listing 4. Create and update a Contact using the REST Web services interface
<?php
// specify the REST web service to interact with
$url = 'http://localhost/sugar/v2/rest.php';
// Open a curl session for making the call
$curl = curl_init($url);
// Tell curl to use HTTP POST
curl_setopt($curl, CURLOPT_POST, true);
// Tell curl not to return headers, but do return the response
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
// Set the POST arguments to pass to the Sugar server
$parameters = array(
'user_name' => 'user',
'password' => 'password',
);
$json = json_encode($parameters);
$postArgs = 'method=login&input_type=json&
response_type=json&rest_data=' . $json;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Close the connection
curl_close($session);
// Convert the result from JSON format to a PHP array
$result = json_decode($response);
// Get the session id
$sessionId = $result['id'];
// Now, let's add a new Contacts record
$parameters = array(
'session' => $session,
'module' => 'Contacts',
'name_value_list' => array(
array('name' => 'first_name', 'value' => 'John'),
array('name' => 'last_name', 'value' => 'Mertic'),
06/08/2015 20:03
4 de 7
http://www.ibm.com/developerworks/library/x-sugarcrmrest/#l3
),
);
$json = json_encode($parameters);
$postArgs = 'method=set_entry&input_type=json&
response_type=json&rest_data=' . $json;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = json_decode($response);
// Get the newly created record id
$recordId = $result['id'];
// Now let's update that record we just created
$parameters = array(
'session' => $session,
'module' => 'Contacts',
'name_value_list' => array(
array('name' => 'id', 'value' => $recordId),
array('name' => 'title', 'value' => 'Engineer'),
),
);
$json = json_encode($parameters);
$postArgs = 'method=set_entry&input_type=json&
response_type=json&rest_data=' . $json;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call, returning the result
$response = curl_exec($session);
// Convert the result from JSON format to a PHP array
$result = json_decode($response);
// Get the record id of the record we just updated
$recordId = $result['id'];
In this Listing 4 example, you just make a second set_entry method call to update the newly created
record. This time you specify the record id of the record you want to update as an entry in the
name_value_list parameter to the Web services method call, and have an entry for each field you are
updating as a part of the call (for this example, you are updating the title field to the value Engineer).
You then make the request, and look for the record id to be returned to you as a sign of a successful
result of the Web service method call.
06/08/2015 20:03
5 de 7
http://www.ibm.com/developerworks/library/x-sugarcrmrest/#l3
The parameters for set_entries are nearly the same as set_entry, except instead of
name_value_list, the parameter is name_value_lists, which is an associative array of the records
you create using the Web services API. The record ids of the created records are returned back in the
ids parameter as an array, and they are given back in the order in which they are passed in the
parameter list.
06/08/2015 20:03
6 de 7
http://www.ibm.com/developerworks/library/x-sugarcrmrest/#l3
$json = json_encode($parameters);
$postArgs = 'method=set_relationship&input_type=json&
response_type=json&rest_data=' . $json;
curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
// Make the REST call
$response = curl_exec($session);
After creating the Account and Contact you wish to relate together, you build the request made to the
set_relationship Web services method call. You then pass the following:
session parameter for the session ID of the Web services session
module_name for the main module of the relationship
module_id for the ID of the record in that module that will be the base of the relationship
link_field_name for the name of the relationship in that module used to link to the other module (in
Summary
In this article, you learned about a new feature in SugarCRM 5.5, which is a REST interface into the
Sugar Web Services framework. After learning a bit about how REST Web services work, you looked at
some examples that took advantage of the REST interface to the Sugar Web services framework. You
saw how to add a new record to a module, and then how to modify that record. You also saw how to add
multiple records in one method call, saving the overhead of making several remote server calls in a row.
Lastly, you saw how to relate two different records together using the set_relationship method of the
Web services framework.
Download
Description
Name
Size
Article examples
rest.php.samples.zip
5KB
Resources
Learn
Sugar Developer Documentation: Check out the detailed guides to the various
SugarCRM APIs.
The Sugar Developer Zone: Find content for all SugarCRM developers.
Forums
Connect your data to the outside world with SugarCRM connectors: Build a
Standards
Google News connector using the Google AJAX Search API (John Mertic,
developerWorks, February 2010): Build an example connector with the
Events
Bluemix Developers
Community
Get samples, articles, product
docs, and community resources
to help build, deploy, and manage
your cloud apps.
developerWorks Weekly
Newsletter
06/08/2015 20:03
7 de 7
http://www.ibm.com/developerworks/library/x-sugarcrmrest/#l3
developerWorks.
PHP.net: Find PHP documentation and put this general-purpose scripting
language to work in your Web development and HTML.
the Recommended PHP reading list: Check out this PHP reading list compiled
for programmers and administrators by IBM Web application developers.
PHP content: Browse PHP-related articles, tutorials, and more on
developerWorks.
PHP project resources IBM developerWorks: Expand your PHP skills.
DevOps Services
Software development in the
cloud. Register today to create a
project.
06/08/2015 20:03