Sharing some ideas and advice on using REST API filter conditionals

Target Audience

I am skipping authentication and the basics of REST. The target audience is the developer who wants to get more out of the API. This page is a good starting point for the REST API and covers the basics skipped in this post. There is plenty to learn about here. Take your time and make use of SugarClub to get advice.

Introduction

I am sharing some of my ideas and advice on using the filter endpoint for the SugarCRM REST API (a.k.a. Web Services).

The focus is on the HTTP POST method as this is the method I prefer when using filters. I find the JSON used to be more readable and that helps me get the results I need.

The idea for the example is a project that needs a list of Leads that have a phone number. The example makes use of the OR conditional and an example of the filter/count endpoint is included.

I am using the operator "$not_empty" here as it is a shortcut to get NOT NULL OR NOT "" results.

The filter endpoint for the REST API maps to the PHP filter API so this guide is a good resource.

The filter endpoint supports GET and POST. The first example is for GET to show the difference in syntax.

Examples

The example below shows a filter using GET and uses the count endpoint to keep it simple.

myinstancename.sugarondemand.com/MODULENAME/count

URL encoding of the parameters is required so the actual request would look like the one below.

https://myinstancename.sugarondemand.com/rest/v11/Leads/filter/count?filter%5B0%5D%5Bphone_work%5D%5B%24not_empty%5D%3D%0A

The count endpoint does not need the list of fields to return or the other parameters required by the filter endpoint.

Next, we have the POST examples.

The filters search for Leads that have something filled in for phone_work or for phone_mobile.

1) Get a count of records.

HTTP method: POST

URL: https://myinstancename.sugarondemand.com/rest/v11/Leads/filter/count

Body (JSON):

{
  "filter": [
    {
      "$or": [
        {
          "phone_work": {
            "$not_empty": ""
          }
        },
        {
          "phone_mobile": {
            "$not_empty": ""
          }
        }
      ]
    }
  ]
}

2) Get actual records, extra parameters are included to collect only the needed fields and to support pagination.

HTTP method: POST

URL: https://myinstancename.sugarondemand.com/rest/v11/Leads/filter

BODY ( JSON):

{
  "filter": [
    {
      "$or": [
        {
          "phone_work": {
            "$not_empty": ""
          }
        },
        {
          "phone_mobile": {
            "$not_empty": ""
          }
        }
      ]
    }
  ],
  "max_num": 2,
  "offset": 0,
  "fields": "id,first_name,last_name,phone_work,phone_mobile,date_entered",
  "order_by": "date_entered",
  "favorites": false,
  "my_items": false
}

Please share any questions as a reply to this discussion.