SugarCRM Cookbook – The School of REST – Part 3

sugarmajed —  February 28, 2014 — 3 Comments

This is the final section of the School of Rest. We’ll be covering filtering on relationships as well as Global Search, Favorites, and Deleting records.

We’ve already created our Account “Burger Palace” in Part 1 and showed how to filter lists with various conditions.

And in Part 2 we created our Contact “Bob Burger” and related him to “Burger Palace”. Now we’ll show how these same concepts apply to relationships.

11. Filtering on Relationships

All the same stuff that we learned for filtering on lists can be applied to relationships as well. Let’s retrieve all the Contacts that are related to “Burger Palace” whose first and last name starts with “B” and who we have marked as a favorite.

To filter on first and last name we know the filter looks like filter[0][first_name][$starts]=B and filter[0][last_name][$starts]=B

But what about favorites? Favorites are a way for users to specify which records are important to them and they have a special filter condition that looks like filter[0][$favorite]=_this

So we will do a GET request to /rest/v10/Accounts/demo_burger_palace/link/contacts?filter[0][last_name][$starts]=b&filter[0][first_name][$starts]=b&filter[0][$favorite]=_this&fields=name,first_name,last_name,email,description

Well that didn’t work to well. First, we need to mark “Bob Burger” as a favorite.

12. Mark a Contact as a Favorite – Bob Burger

All we need to do is a PUT to  /rest/v10/Contacts/demo_bob_burger/favorite

This works on all modules that support favorites, and allows us to quickly filter our favorite records.

You’ll notice in the response the record now says “my_favorite” is true.

If we wanted to unmark a record as a favorite we would just do a DELETE  to /rest/v10/Contacts/demo_bob_burger/favorite

13. Try Step 11 Again!

Let’s re-run the relationship filter from Step 10! Let’s do a GET request to /rest/v10/Accounts/demo_burger_palace/link/contacts?filter[0][last_name][$starts]=b&filter[0][first_name][$starts]=b&filter[0][$favorite]=_this&fields=name,first_name,last_name,email,description

Excellent! Now that’s what we expected!

14. Filter by a Related record

Now, let’s filter our Accounts list for only records that have a contact with the last name “burger”. Our filter condition will look like filter[0][contacts.last_name]=burger and remember that “contacts” in this case is the Link or Relationship Name not the module name.

So let’s do a GET to rest/v10/Accounts?filter[0][contacts.last_name]=burger

curl -X GET \
  'http://server/pro720/rest/v10/Accounts?filter%5B0%5D%5Bcontacts.last_name%5D=burger&fields=name%2Cfirst_name%2Clast_name%2Cemail%2Cdescription' \
  -H 'cache-control: no-cache' \
  -H 'oauth-token: 39ba05eb-2289-4770-ac39-9fe03f99c77a' \
  -H 'postman-token: 65094f2f-ae73-851b-11b1-995e66eb1779'
GET /pro720/rest/v10/Accounts?filter[0][contacts.last_name]=burger&fields=name,first_name,last_name,email,description HTTP/1.1
Host: server
OAuth-Token: 39ba05eb-2289-4770-ac39-9fe03f99c77a
Cache-Control: no-cache
Postman-Token: 598e3c09-43cd-2e7c-704e-0ffbd0378a1e
     "next_offset": -1,
     "records": [
             "id": "demo_burger_palace",
             "name": "Burger Palace",
             "date_modified": "2017-07-28T10:14:29-04:00",
             "description": "My Example Account",
             "locked_fields": [],
             "email": [
                     "email_address": "",
                     "primary_address": true,
                     "reply_to_address": false,
                     "invalid_email": false,
                     "opt_out": false
             "_acl": {
                 "fields": {}
             "_module": "Accounts"

Great! We got “Burger Palace” which is what we wanted.

15. Global Search/Full Text Search 

Now let’s just search everywhere for the word “burger” and see what we get! All we have to do is a GET request to /rest/v10/search?q=burger  and that will search against SugarCRM’s Full Text Search.

We got two records back – “Burger Palace” and “Bob Burger”. So using Global Search/Full Text Search we can search against all of our objects at once!

16.  Let’s Clean Up

All we need to do is a DELETE request to /rest/v10/Accounts/demo_burger_palace

and another DELETE request to /rest/v10/Contacts/demo_bob_burger

And remember there is more documentation at /rest/v10/help

Trackbacks and Pingbacks:

  1. SugarCRM Cookbook – The School of REST – Part 2 « SugarCRM Developer Blog - February 28, 2014

    […] Continue on to Part 3  – Filtering on Relationships, Favorites, and Deleting Records  […]

  2. SugarCRM Cookbook – The School of REST – Part 1 « SugarCRM Developer Blog - February 28, 2014

    […] Part 3  – Filtering on Relationships, Favorites, and Deleting Records  […]

  3. How to filter on related fields using Filter API « Sugar Developer Blog – SugarCRM - February 27, 2017

    […] it before, have a look at this documentation for detailed information about how filters work: – […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s