Filtering requests

Tags: Flow

Overview

The Flow API is built using the Django REST Framework and supports basic and enhanced filtering options. Most operators are supported. The Django REST framework documentation is available here: http://www.django-rest-framework.org/api-guide/filtering/

Basic filter options

Flow can filter using standard REST syntax using the object ID.

For example, to obtain a specific user record, you would submit the following request:

https://flow.pluralsight.com/v3/customer/core/users/?id=1234567890

Where:  

“1234567890” is the specific User Id being requested.   

Field Inclusion and Omission

The API provides a mechanism to limit the fields returned for a given object using the FIELDS  and OMIT  keywords. This can help with performance and limit the scope of data sent to the client application.

Fields Keyword

To limit the response to a specific set of fields, use the FIELDS  keyword and provide a comma-separated list of field names.

Here’s an example:


https://flow.pluralsight.com/v3/customer/core/users/?fields=id,name,email&limit=3 

This will return three user records with only the id, name, and email fields.

Omit Keyword

To limit the fields to a select few, use the OMIT keyword and provide a comma-separated list of field names.

Here’s an example:

https://flow.pluralsight.com/v3/customer/core/users/?omit=email,teams

This will return all fields in the USERS  object with the email and teams fields omitted:

Enhanced filter options

In addition to providing basic filtering options, the Flow API offers enhanced filtering capabilities that allow you to filter objects using complex filter operations. These filter options can greatly improve performance by returning precisely the objects you want.  

There are several built-in filter options for searching:

gt

Filters for records that are greater than the specified value.

Example

All commits whose lines of new_work code is greater than 100000.

Request

https://flow.pluralsight.com/v3/customer/core/commits/?new_work__gt=100000

Response:

gte

Filters for records that are greater than or equal to the specified value.

Example

All COMMITS  whose lines of new work code greater than or equal to 2695.

Request:


https://flow.pluralsight.com/v3/customer/core/commits/?new_work__gte=2695

 Response:

lt

Filters for records that are less than the specified value.

Example

All COMMITS  whose lines of new work code less than 10.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?new_work__lt=10

Response:

lte

Filters for records that are less than or equal to the specified value.

Example

All COMMITS  whose lines of new work code is less than or equal to 1.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?new_work__lte=1

Response:

in

Filters for records that are in a list of specified values.

Example

Repository ID in 168294.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?repo_id__in=168294

Response:

icontains

A case-insensitive string containment test equivalent to ILIKE “%foo%’ in SQL.

Example

Commit message that contains the word “progress”.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?message__icontains=progress

Response:

startswith

A case-sensitive search for records that start with the specified string.  

Example

User name contains “george”.

Request:

https://flow.pluralsight.com/v3/customer/core/users/?name__startswith=george

Response:

between

Filters for records that fall within the specified range of values. Flow does not currently have a between filter. You use __gte and __lt filters to create a 'between'.

Example

Commits created between June 8, 2018 and June 15, 2018.

Request:


https://flow.pluralsight.com/v3/customer/core/commits/?author_date__gte=2018-06-08&author_date__lt=2018-06-15

Response:

equals

A case-sensitive exact string match.

Example

Repository vendor type is “github”.

Request:

https://flow.pluralsight.com/v3/customer/core/repos/?vendor_type=github

Response:

not equal to

A case-sensitive match for all records that are not an exact string match.

Example

Repository vendor type is not “github”.

Request:

https://flow.pluralsight.com/v3/customer/core/repos/?vendor_type!=github

Response:

remove_excluded

Filters for COMMITS  that are not flagged as being excluded.

Example

All COMMITS  except those with excluded Users..

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?remove_excluded=true

Response:

smart_dedupe

Excludes duplicate COMMITS .

The Flow de-duplication ensures unique commit is represented once and only once. Certain branching/merging activities can cause git to create multiple HexSHA’s for the same work. This makes sure you don’t double count.

Example

All COMMITS ; no duplicate records.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?smart_dedupe=true

exclude_weekends

Filters for COMMITS  committed on weekdays (Monday – Friday).  

Example

All COMMITS  except those created on a Saturday or Sunday.

Request:


https://flow.pluralsight.com/v3/customer/core/commits/?exclude_weekends=true

Response:

exclude_outliers

Filters for COMMITS  that have been marked as outliers. For more information about outliers, see our help document.

Example

All COMMITS  that have been excluded due to outlier detection.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?exclude_outliers=true

Response:

exclude_blocked

Filters for COMMITS  that are not associated with blocked or unprocessed repos.

Example

COMMITS  with no blocked repos.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?exclude_blocked=true

Response:

normalize_authors

Replaces all User IDs with their respective main alias record.

Example

All COMMITS ; User alias ID matching main, apex user ID.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?normalize_authors=true

Response:

apply_default_filters

Applies the default set of filters: smart_dedupe, exclude_outliers, exclude_pr_orphans, exclude_merge, and exclude_blocked.

This will give you the best match to Flow's reports.

Example

All COMMITS  except those matching the default filters.

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?apply_default_filters=true

Response:

Customizing results

Filtering your requests helps to restrict the data that is reported, but the results you “GET” can still be too sizeable to manage. Customizing your results helps to keep the data concise—a very good thing!

Ordering

You can use ordering to alter the sort order/type of the results. Place a "-" in front of the parameter you are ordering by to get results in descending order.

Example

&ordering=-id

Request:

https://flow.pluralsight.com/v3/customer/core/commits/?fields=id,new_work,churn&limit=5&ordering=id

Response:

Pagination

Flow uses limit and offset pagination options:

  • limit – restricts the results to a specific number of data rows. For example, setting limit to 5 means that the system only returns the first five rows in the matching record set.  

  • offset – indicates where to start the results. A common practice is to combine this option with limit. For example, you could limit the request to only 50 records and specify an offset of 10, which would result in results of records 11 to 50.

Pretty easy stuff, right? How about an example with multiple result options?

Request:

https://flow.pluralsight.com/v3/customer/core/users/?fields=id,name&ordering=name&limit=5

Response:

The request with multiple options returns nice and clean results, but there are three important things about the response that should catch your attention:

  • Although there is a count of 22598 records, the response shows only five records, as we requested.
  • Instead of returning all user fields, the system has returned the two we wanted: id and name.
  • The records are in alpha order since we specified order by name.


back to top


If you need help, please email support@pluralsight.com for 24/7 assistance.