Post originally written by sugarmajed.
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]=BBut 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]=_thisSo 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
CURL Filter Relationships.sh
curl -X GET -H OAuth-Token:8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4 -H Cache-Control:no-cache -H Postman-Token:a86bc38a-8c3f-d364-fbfe-282e41b10645 http://server/pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?filter[0][last_name][$starts]=b&filter[0][first_name][$starts]=b&filter[0][$favorite]=_thisGET Filter Relationships.http
GET /pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?filter%5B0%5D%5Blast_name%5D%5B%24starts%5D=b&filter%5B0%5D%5Bfirst_name%5D%5B%24starts%5D=b&filter%5B0%5D%5B%24favorite%5D=_this HTTP/1.1
Host: server
OAuth-Token: 8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4
Cache-Control: no-cache
Postman-Token: fc8df8eb-c475-28bc-ca03-6b7ee511a069
Response.json
{
"next_offset": -1,
"records": []
}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.
CURL PUT Favorite Contact.sh
curl -X PUT -H OAuth-Token:8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4 -H Cache-Control:no-cache -H Postman-Token:69fc3540-0acd-0186-c0c9-cb95ac352bd8 -H Content-Type:multipart/form-data; boundary=----WebKitFormBoundaryp7MA4YWxkTrZu0gW http://server/pro720/rest/v10/Contacts/demo_bob_burger/favorite
PUT Favorite Contact.http
PUT /pro720/rest/v10/Contacts/demo_bob_burger/favorite HTTP/1.1
Host: server
OAuth-Token: 8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4
Cache-Control: no-cache
Postman-Token: cb2d99d7-241d-e4e2-71b3-f9a432d72a12
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryp7MA4YWxkTrZu0gW
Response.json
{
"id": "demo_bob_burger",
"name": "Bob Burger",
"date_entered": "2014-02-25T12:16:41-08:00",
"date_modified": "2014-02-25T12:21:22-08:00",
"modified_user_id": "1",
"modified_by_name": "Administrator",
"created_by": "1",
"created_by_name": "Administrator",
"doc_owner": "",
"user_favorites": [
"1"
],
"description": "Bob Burger was updated",
"deleted": false,
"assigned_user_id": "",
"assigned_user_name": "",
"team_count": "",
"team_name": [
{
"id": 1,
"name": "Global",
"name_2": "",
"primary": true
}
],
"email": [
{
"email_address": "bob.burger@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
}
],
"email1": "bob.burger@example.com",
"email2": "",
"invalid_email": false,
"email_opt_out": false,
"salutation": "",
"first_name": "Bob",
"last_name": "Burger",
"full_name": "Bob Burger",
"title": "",
"facebook": "",
"twitter": "",
"googleplus": "",
"department": "",
"do_not_call": false,
"phone_home": "",
"phone_mobile": "",
"phone_work": "",
"phone_other": "",
"phone_fax": "",
"primary_address_street": "",
"primary_address_street_2": "",
"primary_address_street_3": "",
"primary_address_city": "",
"primary_address_state": "",
"primary_address_postalcode": "",
"primary_address_country": "",
"alt_address_street": "",
"alt_address_street_2": "",
"alt_address_street_3": "",
"alt_address_city": "",
"alt_address_state": "",
"alt_address_postalcode": "",
"alt_address_country": "",
"assistant": "",
"assistant_phone": "",
"picture": "",
"email_and_name1": "",
"lead_source": "",
"account_name": "Burger Palace",
"account_id": "demo_burger_palace",
"dnb_principal_id": "",
"opportunity_role_fields": "",
"opportunity_role_id": "",
"opportunity_role": "",
"reports_to_id": "",
"report_to_name": "",
"birthdate": "",
"campaign_id": "",
"campaign_name": "",
"c_accept_status_fields": "",
"m_accept_status_fields": "",
"accept_status_id": "",
"accept_status_name": "",
"accept_status_calls": "",
"accept_status_meetings": "",
"sync_contact": false,
"mkto_sync": false,
"mkto_id": null,
"mkto_lead_score": null,
"my_favorite": true,
"_acl": {
"fields": {}
},
"following": true,
"_module": "Contacts"
}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
CURL filter relationships again.sh
curl -X GET -H OAuth-Token:d1645103-c562-e439-c0d0-530d2f4e3801 -H Cache-Control:no-cache -H Postman-Token:4ab308ee-7902-6a3f-dc9c-f8bb595dec97 http://server/pro720/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
GET Filter Relationships Again.http
GET /pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?filter%5B0%5D%5Blast_name%5D%5B%24starts%5D=b&filter%5B0%5D%5Bfirst_name%5D%5B%24starts%5D=b&filter%5B0%5D%5B%24favorite%5D=_this&fields=name%2Cfirst_name%2Clast_name%2Cemail%2Cdescription HTTP/1.1
Host: server
OAuth-Token: d1645103-c562-e439-c0d0-530d2f4e3801
Cache-Control: no-cache
Postman-Token: 8ee8836c-e7c4-51e8-a187-bbfd92e6a790
Response.json
{
"next_offset": -1,
"records": [
{
"id": "demo_bob_burger",
"name": "Bob Burger",
"date_modified": "2014-02-25T15:03:01-08:00",
"description": "Bob Burger was updated",
"email": [
{
"email_address": "bob.burger@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
}
],
"first_name": "Bob",
"last_name": "Burger",
"_acl": {
"fields": {}
},
"_module": "Contacts"
}
]
}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": "burgers@example.com",
"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.
CURL Full Text Search.sh
curl -X GET -H OAuth-Token:4ef8594d-5b45-20f4-0a01-530d20d69d1f -H Cache-Control:no-cache -H Postman-Token:e76d2d29-bc10-bea7-c2b6-761e49a8a197 http://server/ent720/rest/v10/search?q=burger&fields=name,email,description
GET Full Text Search.http
GET /ent720/rest/v10/search?q=burger&fields=name%2Cemail%2Cdescription HTTP/1.1
Host: server
OAuth-Token: 4ef8594d-5b45-20f4-0a01-530d20d69d1f
Cache-Control: no-cache
Postman-Token: 7aeedc64-602a-535d-7c0d-b32bf2e1a035
Response.json
{
"next_offset": -1,
"records": [
{
"id": "demo_bob_burger",
"name": "Bob Burger",
"date_modified": "2014-02-25T23:03:01+00:00",
"description": "Bob Burger was updated",
"email": [
{
"email_address": "bob.burger@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
}
],
"_acl": {
"fields": {}
},
"_module": "Contacts",
"_search": {
"score": 1,
"highlighted": {
"last_name": {
"text": "<strong>Burger</strong>",
"module": "Contacts",
"label": "LBL_LAST_NAME"
}
}
},
"following": true
},
{
"id": "demo_burger_palace",
"name": "Burger Palace",
"date_modified": "2014-02-25T23:01:42+00:00",
"description": "My Example Account",
"email": [
{
"email_address": "burgers@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
}
],
"_acl": {
"fields": {}
},
"_module": "Accounts",
"_search": {
"score": 1,
"highlighted": {
"name": {
"text": "<strong>Burger</strong> Palace",
"module": "Accounts",
"label": "LBL_NAME"
},
"email1": {
"text": "<strong>burgers</strong>@example.com",
"module": "Accounts",
"label": "LBL_EMAIL_ADDRESS"
}
}
},
"following": true
}
]
}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!