Code fundamentals API

Tags: Flow

The Code fundamentals API provides the metrics in the Code fundamentals report for use outside of Flow. 

Note: This endpoint is not documented in Flow's interactive API documentation.

Who can use this?

 Core
Plus
 
   

 

The API gives you averages for a time period or weekly values for the four Code fundamentals metrics: Coding days, Commits per day, Impact, and Efficiency.

If you haven’t used the Flow customer API before, learn more about how to make a Flow API call


Giving permissions for the Code fundamentals API

Each user who calls the API needs to have the Code Fundamentals API permission. To enable API permissions for users, make sure you have the permission Manage User Permissions enabled.

To enable the Code Fundamentals API permission:

  1. Under Settings, go to the Users page.
  2. Search for the user you want to grant the Code Fundamentals API permission to.
  3. Click on the user’s name.
  4. Click on the Access tab.
  5. In the API access column, check the box next to Code Fundamentals API.
  6. Click Save changes.
  7. Repeat this process for all users you want to be able to access the Code Fundamentals API.

Note: Making these changes does not affect existing permissions for the other Flow customer APIs.  

In addition to having the Code Fundamentals API permission, each user who wants to call the API must have a valid API key specific to that user. Learn more about creating API keys in Flow.

Important: If a user has either the Code Fundamentals API permission or an API key on their account, but not both, they will be unable to use the Code Fundamentals API. If you’re unable to call the Code Fundamentals API, verify your user has both the permission and a valid API key.

back to top


Calling the API

Call the API endpoint over standard HTTPS. Use any tool/programming language that can add the authorization: bearer <API Key> header.

The base URL for this API is: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/

back to top


Supported parameters

ParameterRequired or OptionalDescriptionExample
start_dateRequiredThe start of the date range.start_date=2021-05-01
end_dateOptionalThe end date of the date range. If not specified, the current date will be used.end_date=2021-05-15
include_nested_teamsOptionalDetermines whether data from nested teams are included.

include_nested_teams=true

include_nested_teams=false


aggregateOptionalMatch users/teams visible at aggregate depth. This will show anonymized aggregate metrics without individually identifiable details.

aggregate=true

aggregate=false


atomicOptionalMatch users/teams visible at atomic depth. This will show granular or individually identifiable details in metrics, if you have the rights to see them.

atomic=true

atomic=false


resolutionRequired

This parameter specifies the level of details returned: 

  • period returns averages for each metric over the given date range. 
  • week returns details for each week over the given date range.

resolution=week

resolution=period


apex_user_idOptionalMatch on the ID of a specific apex user.apex_user_id=12345
apex_user_id__inOptionalMatch on a set of provided apex user IDs.apex_user_id__in=12,34,56
team_idOptionalMatch on ID of a specific Flow team.team_id=12345
team_id__inOptionalMatch on a set of provided Flow team IDs.team_id__in=21,34,65,67
repo_idOptionalMatch on exact repo ID.repo_id=12345
repo_id__inOptionalMatch on a set of provided repo IDs.repo_id__in=1,2,3,4
repo_id_not__inOptionalMatch on a all repo IDs except the provided repo ID set.repo_id_not__in=67,45,34
repo_tag_idOptionalMatch on an exact repo tag ID.repo_tag_id=5123
repo_tag_id__inOptionalMatch on a set of provided repo tag IDs.repo_tag_id__in=34,21,78,45
repo_nameOptionalMatch on any repo name which contains the search parameter.repo_name=ExampleTeam


back to top


Result formats

The result format returned by the API is in JSON. The shape of the data depends on the resolution flag.

If the resolution flag is set to week, then the results are: 

{

    "count": 5,

    "results": [

        {

            "period_start_date": "2021-05-31",

            "active_days": 2.2,

            "commit_count": 4.2,

            "total_impact": 94.1,

            "total_efficiency": 78.1

        },

        {

            "period_start_date": "2021-06-07",

            "active_days": 2.8,

            "commit_count": 5.5,

            "total_impact": 111.1,

            "total_efficiency": 58

        },

        {

            "period_start_date": "2021-06-14",

            "active_days": 2.9,

            "commit_count": 3.7,

            "total_impact": 114.4,

            "total_efficiency": 65.1

        },

        {

            "period_start_date": "2021-06-21",

            "active_days": 2.7,

            "commit_count": 3.9,

            "total_impact": 122.9,

            "total_efficiency": 76.9

        },

        {

            "period_start_date": "2021-06-28",

            "active_days": 1.6,

            "commit_count": 5.7,

            "total_impact": 85.1,

            "total_efficiency": 65.4

        }

    ]

}

Weeks with no data are omitted from the results.

If the resolution flag is set to period, the shape of the data is:

{

    "count": 1,

    "results": [

        {

            "active_days": 2.8,

            "commit_count": 4.5,

            "total_impact": 121.7,

            "total_efficiency": 68.2

        }

    ]

}

Error format

If there is an error in any of the request parameters, the shape of the response is:

{

    "start_date": 

        ["Provide a valid date. Date cannot be more than 3 years prior to now."], 

    "aggregate": 

        ["Provide a valid choice. 'yes' is not one of the available choices: ['true', 'false']"], 

    "resolution": 

        ["Provide a valid choice. 'month' is not one of the available choices: ['period', 'week']"]

}

If there is an error in the request parameters, the system returns a non-200 status code in addition to the response above. This is normally a 400 error for any form of input error, and a 500 error for any back-end exceptions. For back-end exceptions, there is a more generic error like:  

{

    "error": ["Unknown error occurred"]

}

back to top


Examples

Get Code fundamentals for a team

First, use the Teams API endpoint to get your team ID. This looks something like: https://flow.pluralsight.com/v3/customer/core/teams/?name=ExampleTeam. In the response, note the id for the team for use in the next step.

The response for this query is:

{

  "count":1,

  "next":null,

  "previous":null,

  "results":[

    {

      "id":12345,

      "name":"ExampleTeam",

      "description":"",

      "org":1234,

      "avatar":null,

      "vendor":null,

      "created_at":"2020-09-22T15:55:26.482759",

      "parent":54321,

      "path":"11188.99591.52870",

      "ancestors":["ParentTeam","AnotherTeam","ExampleTeam"],

      "visibility":"SHOW",

      "team_level":3,

      "inherited_depth":"atomic",

      "nested_teams":0,

      "all_users":4,

      "unnested_users":4,

      "depth":"inherit"

    }

  ]

}

To get the overall average of the four Code fundamentals for your team for the desired period, use the team ID in the team_id parameter of the Code fundamentals API endpoint and set resolution to period. This query looks like: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&team_id=12345&include_nested_teams=true&resolution=period.

The response for this query looks like:

{

  "count": 1, 

  "results": [

    {

      "active_days": 2.4, 

      "commit_count": 3.5, 

      "total_impact": 97.7, 

      "total_efficiency": 83.1

    }

  ]

}

To get the weekly averages of the Code fundamentals metrics for your team over the desired period, use the team ID in the team_id parameter of the Code fundamentals API endpoint and set resolution to week. The query looks like: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&team_id=12345&include_nested_teams=true&resolution=week.

Note: Any weeks with no commit activity will be excluded from the response. 

The response for this query looks like.

{

        "count": 5,

        "results": [

            {

                "period_start_date": "2021-05-31",

                "active_days": 1.0,

                "commit_count": 4.0,

                "total_impact": 18.5,

                "total_efficiency": 52.6

            },

            {

                "period_start_date": "2021-06-07",

                "active_days": 1.0,

                "commit_count": 4.0,

                "total_impact": 33.8,

                "total_efficiency": 94.9

            },

            {

                "period_start_date": "2021-06-14",

                "active_days": 3.0,

                "commit_count": 3.5,

                "total_impact": 118.0,

                "total_efficiency": 91.4

            },

            {

                "period_start_date": "2021-06-21",

                "active_days": 2.5,

                "commit_count": 4.0,

                "total_impact": 151.7,

                "total_efficiency": 78.1

            },

            {

                "period_start_date": "2021-06-28",

                "active_days": 3.0,

                "commit_count": 2.3,

                "total_impact": 87.4,

                "total_efficiency": 77.9

            }

        ]

    }

Get Code fundamentals for an individual

To get the Code Fundamentals metrics for a single user, first use the Users endpoint of the Flow customer API to get the Apex user ID for the user. The query will look like https://flow.pluralsight.com/v3/customer/core/users/?team_member=12345. Note the id for the user you want to see the Fundamentals metrics for. 

Note: In this example, the team ID from the last example is used to find the Apex user ID. Your request may look different if you use a different parameter to find the Apex user ID for your user. 

The response looks like:

{

    "count": 4,

    "next": null,

    "previous": null,

    "results": [

        {

            "id": 1234567,

            "name": "Stephanie Ventura",

            "email": "stephanie-ventura@examplecompany.com",

            "hidden_from_reports": false,

            "org_id": 1234,

            "created_at": "2019-06-24T21:50:40.880538",

            "teams": [

                {

                    "id": 12345,

                    "name": "ExampleTeam",

                    "description": "",

                    "org": 1234,

                    "avatar": null,

                    "vendor": null,

                    "created_at": "2020-09-22T15:55:26.482759",

                    "parent": 54321,

                    "path": "11188.99591.52870",

                    "visibility": "SHOW",

                    "inherited_depth": null,

                    "nested_teams": 0,

                    "all_users": 4,

                    "unnested_users": 4,

                    "depth": "inherit"

                },

                {

                    ...

                }

            ],

            "has_login": true,

            "pending_invitation": false,

            "alias_count": 8,

            "last_activity_at": "2021-08-09T12:24:18",

            "first_activity_at": "2019-06-24T19:13:02.504000",

            "avatar_url": "https://secure.gravatar.com/avatar/example.jpg?s=96&d=retro&r=g",

            "avatar_exists": false,

            "invitation_id": null,

            "login_enabled": true,

            "is_saml": true,

            "is_group_member": false,

            "hidden": false,

            "hidden_by": null,

            "hidden_at": "2020-11-17T04:07:57.948366",

            "login": {

                ...

            }

        },

        {

            ...

        },

        {

            ...

        },

        {

            ...

        }

    ]

}

Once you have the Apex user ID, you can use it to get the overall average of the four Code fundamentals metrics across the desired period. Use the apex_user_id parameter and set resolution to period. An example query is: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&apex_user_id=1234567&resolution=period.

The response looks like:

{

        "count": 1,

        "results": [

            {

                "active_days": 3.3,

                "commit_count": 4.2,

                "total_impact": 154.9,

                "total_efficiency": 71.1

            }

        ]

    }

To get the weekly averages for the metrics, use the apex_user_id parameter and set resolution to week. An example query is: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&apex_user_id=1234567&resolution=week.

The response looks like:

{

    "count": 5,

    "results": [

        {

            "period_start_date": "2021-05-31",

            "active_days": 2.8,

            "commit_count": 3.9,

            "total_impact": 123.8,

            "total_efficiency": 76.2

        },

        {

            "period_start_date": "2021-06-07",

            "active_days": 3.0,

            "commit_count": 5.1,

            "total_impact": 136.6,

            "total_efficiency": 60.3

        },

        {

            "period_start_date": "2021-06-14",

            "active_days": 3.2,

            "commit_count": 3.9,

            "total_impact": 141.2,

            "total_efficiency": 67.1

        },

        {

            "period_start_date": "2021-06-21",

            "active_days": 3.2,

            "commit_count": 3.6,

            "total_impact": 168.4,

            "total_efficiency": 79.3

        },

        {

            "period_start_date": "2021-06-28",

            "active_days": 2.1,

            "commit_count": 4.4,

            "total_impact": 99.3,

            "total_efficiency": 74.1

        }

    ]

}

back to top


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