API guide: Code fundamentals metrics

Tags: Flow

Overview

This document is intended for developers who are utilizing the Customer API to build code fundamental metrics in their own systems. At Flow, we’re so excited to see what you can do with your creativity and our Customer API. As you’re getting started, we want to make sure that you have a strong foundation in the basics, so we’ll introduce you to how to use the API to get the code fundamental metrics that you see in GitPrime. This document is intended to help you through the API calls necessary to complete a specific task. It’s not intended to replace awesome documentation, so be sure to review the Interactive Documentation.

Getting code fundamental metrics from the API

Step 1: Fetch your users

The first step towards pulling fundamental metrics for your team is to use the users endpoint to grab the ID’s for the users in the team. When multiple user records are associated with an individual, due to differences in email or variations in a name for example, user records can be merged under a single apex user record. The call below gets you a list of apex user id’s and the associated names for everyone in the team!

https://HOSTNAME/v3/customer/core/users/?limit=1000&team__name=YOUR_TEAM_NAME&fields=id,name
  • YOUR_TEAM_NAME : This is the Flow team for which you are trying to get fundamental data
  • HOSTNAME is the IP address or URL for the Flow application. If you’re using the cloud instance of Flow, this will be flow.pluralsight.com. If you’re using an on-premise version of Flow, this will be something other than flow.pluralsight.com.

Your results will look something like this:


{   
       "count" : 20 , //total number of Users that met your criteria
       "next" : null , // NOTE: If you had more than 1000 Users, 
                      //this tag would help you get the rest of them 
      "previous" : null ,
      "results" : [ 
         { 
           "id" : 20812395 ,
           "name" : "Sally Smith"
         }, 
       ... 
        {  
          "id" : 3335303 ,'
          "name" : "Jess Palmere" 
        }
    ]
}

Step 2: Get data for your users

Once you have your list of users ( user_list ), you are ready to go and grab the rest of your data!

Use this call to get the commit data you need:


https://HOSTNAME/v3/customer/core/commits.agg/?limit=1000&apex_user_id__in=YOUR_USER_LIST&is_merge=false&is_pr_orphan=false&haloc__lt=1000&exclude_outliers=true&smart_dedupe=true&author_local_date__gte=START_DATE&author_local_date__lt=END_DATE&aggregate[count]=id&aggregate[sum]=haloc,churn,impact&group_by[apex_user_id,author_local_date__date]
  • HOSTNAME : Use the same hostname as you used in Step 1.
  • YOUR_USER_LIST: This list of User ID’s that you got from Step 1. It should be comma separated.
    • &apex_user_id__in=101,102,445
  • START_DATE/END_DATE: Select your start and end dates
    • This example uses author_local_date which gives you the time local to the User. You can use author_date if you prefer UTC. '
    • Flow Fundamentals reports segment data by week, so for best matching to Flow reports, select full weeks, starting Monday ending Sunday. Make sure you include Sunday. To get the Monday, July 2-Sunday, July 8, use the following:
    • &author_local_date__gte='2018-07-02'&author_local_date__lt='2018-07-09'
Important: This request limits the results set to 1000 records. If you have more than 1000 records to return, you can raise this limit or use the pagination feature. You’ll know you’ve hit this case because the “count” that is returned is > 1000. The “next” tag will give you the URL to get the or next set of your data! See the example below.

"count" : 1331, 
"next": "https://HOSTNAME/v3/customer/core/commits.agg/?aggregate%5Bcount%5D=id&aggregate%5Bsum%5D=haloc2C+churn%2C+impact+&apex_user_id__in=YOUR_USER_LIST&author_local_date__gte=START_DATE&author_local_date__lt=END_DATE&group_by%5Bapex_user_id%2C+author_local_date__date%5D=&haloc__lt=1000&is_merge=false&is_pr_orphan=false&limit=5&offset=1000&smart_dedupe=true"

Step 3: Put it all together

Now you have the following data, go crazy and do some cool stuff! To create a weekly time series similar to Flow’s fundamentals report, go through each user and each week and calculate:


Per User:

  • Coding Days per Week
    • For each week count the number of days when the user committed data.
  • Commits per Coding Day
    • For each week, sum(id_count)/Coding Days
  • Impact
    • For each week, sum( impact_sum )
  • Efficiency
    • For each week calculate efficiency across all commits by each User 100*(1-sum( churn_sum )/sum( haloc_sum ))

There are lots of ways to aggregate this data for multiple weeks or for a team.  This is how we do it in our reports:

For each week:

Step 1:  Create the totals/averages for each apex user (see above).

Step 2: Average the totals for any user on the team that contributed that week.

  • Coding Days per Week
    • sum (coding days per contributor)/active contributors
  • Commits per Coding Day
    • sum(average contributor commits per day)/active contributors
  • Impact
    • sum( impact_sum per contributor)/active contributors
  • Efficiency
    • sum(efficiency per contributor)/active contributors

After each week is calculated, you can average the weeks together to get the overall totals. This will match most closely to our reports if you utilize full weeks (Monday through Sunday).

back to top


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