API guide: LoC by PR

Tags: Flow

Overview

This tutorial will walk you through how to grab total lines of code (LoC) submitted in a PR. Use this data to then calculate median or average LoC by PR.

Because LoC is associated with commits, you will need to use two endpoints, commits and pull_requests, to get the data we need.

Step 1: Grab the PRs

This first API call will be our main source of information for all the other API calls in this guide. The below call will return all merged PRs within the START_DATE and END_DATE you designate.


https://HOSTNAME/v3/customer/core/pull_requests/?closed_at__gte=START_DATE&closed_at__lte=END_DATE&fields=id,project_id,commit_shas,created_at,created_by_id,title,closed_at,state&state=merged&group_by[created_by_id]
  • 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.
  • START_DATE/END_DATE: Select your start and end date. Notice we are using the "closed_at" filters which will only return PRs that are closed or merged.

You will see, by PR, the following fields grouped by PR author (created_by_id)

  • PR ID = id
  • Project_id – Project id.
  • Commit Shas – associated commits shas for each PR
  • Created_at = date at which the PR was created
  • Created_by_id – Alias who created the PR
  • PR Title – Title of PR
  • Closed_at = date at which the PR was closed
  • State – state of PR, this should be “merged” since that is what we are filtering for

If you want to include merged AND closed PRs you can remove the filter "&state=merged' and the API call will automatically include any PR that were merged or closed during your date range.

You can export this data into excel by adding &format=csv at the end of the query. Use this document to guide you through the processes of opening it in an excel spreadsheet.

Note: If you are interested in calculating PR LoC by User continue to the Step 2, otherwise move on to Step 3.

Step 2: Grab the user information

Next you will want map the created_by_id to the actual user. In order to do that you need to grab all created_by_id’s from Step 1 and run it through the user_alias endpoint to grab the user information.


https://HOSTNAME/v3/customer/core/user_alias/?id__in=YOUR_USER_ID_LIST&fields=id,name,apex_user
  • YOUR_USER_ID_LIST: This is the list of created_by_ids from Step 1. They should be in a comma separated list.

This will return a consolidated list of all the users with their name and apex_user_id which you can now map to your original list of PR created_by_ids.

Step 3: LoC by PR

There are two ways you can grab the commit level data associated with your PRs. You will need to do this for each of your PRs, so writing a script may be in your best interest.

Option A: Take all the commit_shas associated with a PR from Step 1 and place them in the following API call.


https://HOSTNAME/v3/customer/core/commits.agg/?hexsha__in=YOUR_COMMIT_SHA_LIST&aggregate[sum]=haloc
  • YOUR_COMMIT_SHA_LIST : This is a comma separated list of commit shas for all PRs from Step 1.

This list of commit_shas will look something like this from Step 1:


<list-item><id>223488875</id>
<title>Testing Applications</title>
<state>merged</state> 
<project_id>2745555</project_id> 
<closed_at>2019-07-09T21:40:00</closed_at>
<commit_shas>
    <list-item>0ee0aed269ade4ab10007a8b0190ec0a764d880d</list-item>
    <list-item>ab0597448bb52e223d761ef7e890046221a1f476</list-item>
    <list-item>93465fdf00488d21d45f9dd803d52fbb5b33d704</list-item>
    <list-item>b531787c86337a5c0b9b7ccb5e44862bb6e70d7c</list-item>
    <list-item>35c145f42e378f7946e871a43cd9a3dcd525b3cc</list-item>
    <list-item>3f6c0180a0bcae0b6846a8e4f3f5c7a5747fa096</list-item>
    <list-item>b8005a09f43534ddc25e9f8015a2619753e27d51</list-item>
</commit_shas>
<created_at>2019-06-24T19:39:08</created_at>
<created_by_id>6666896</created_by_id>

This option will aggregate the total LoC (HALOC) across all commits_shas that you used in the API call.

Your results will look something like this:


<count>1</count> 
<next/><previous/> 
<results> 
  <list-item>
        <haloc_sum>19</haloc_sum>
  </list-item></results>
<records>1</records>

Where haloc_sum will be the total LoC for the PR.

Option B: You can use the PR ID in the commits endpoint to identify any associated commits.

https://HOSTNAME/v3/customer/core/commits/?pull_request_id=PULL_REQUEST_ID&fields=hexsha,haloc,id
  • PULL_REQUEST_ID: This is the <id> for the PR from Step 1

The above API query will return a list of commit shas that are associated with the PR. It will show you the hexsha, HALOC (LoC) by commit and the commit ID.

If you wanted to aggregate the HALOC across these commits you can do so using this API call:

https://HOSTNAME/v3/customer/core/commits.agg/?pull_request_id=PULL_REQUEST_ID&aggregate[sum]=haloc

Once you run through each of your PRs and grab the total LoC (HALOC) you can then calculate the average or median LoC per PR.

back to top


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