stackalytics/doc/source/userdoc/api_v1.0.rst

Stackalytics JSON API v1.0

Note

JSON API v1.0 corresponds to Stackalytics v0.X

1 General API information

This section contains base info about the Stackalytics JSON API design.

1.2 Request / Response Types

The Stackalytics API default response format is "application/json". However if HTTP attribute 'callback' is specified then JSONP response is returned. That allows to use response in client-side code and avoid same-host requests limitations.

Example:

GET /api/1.0/stats/companies

or

GET /api/1.0/stats/companies?callback=myCallback
Accept: application/javascript

1.3 Faults

The Stackalytics API returns an error response if a failure occurs while processing a request. Stackalytics uses only standard HTTP error codes. 4xx errors indicate problems in the particular request being sent from the client and 5xx errors indicate server-side problems.

2 Methods

2.1 Common Parameters

All requests support common set of parameters that allow to filter resulting data.

Parameter	Description
release	Name of OpenStack release or 'all', by default current release
project_type	Type of project, by default 'openstack'
module	Name of module (repository name)
company	Company name
user_id	Launchpad id of user or email if no Launchpad id is mapped.
metric	Metric: e.g. 'commits', 'loc', 'marks', 'emails'

2.1.1 Other query parameters

Data can be queried by time period:

Parameter	Description
start_date	When the period starts
end_date	When the period ends

Both start_date and end_date take as their argument Unix time

For example to specify 'Thu Jan 1 00:00:00 UTC 2015' the value would be 1420070400

Note that if both release and time period are specified then the data is selected for the intersection (thus the useful way is to specify release as all).

2.2 Contribution by Modules

Description

Stats on contribution per modules. The data contains list of modules with their metric. Modules which metric is 0 are omitted.

Request

Verb	URI	Description
GET	/api/1.0/stats/modules	Contribution by Modules

Example Request

GET /api/1.0/stats/modules?release=havana&metric=commits&project_type=openstack&user_id=zulcss

Example Response

{
    "stats": [
        {
            "metric": 18,
            "id": "oslo-incubator",
            "name": "oslo-incubator"
        },
        {
            "metric": 7,
            "id": "keystone",
            "name": "keystone"
        },
        {
            "metric": 1,
            "id": "python-neutronclient",
            "name": "python-neutronclient"
        }
    ]
}

2.3 Contribution by Companies

Description

Stats on contribution per companies. The data contains list of companies with their metric. Companies which metric is 0 are omitted.

Request

Verb	URI	Description
GET	/api/1.0/stats/companies	Contribution by Companies

Example Request

GET /api/1.0/stats/companies?release=havana&metric=commits&project_type=openstack&module=neutron

Example Response

{
    "stats": [
        {
            "metric": 155,
            "id": "VMware",
            "name": "VMware"
        },
        {
            "metric": 76,
            "id": "Mirantis",
            "name": "Mirantis"
        },
        {
            "metric": 53,
            "id": "Red Hat",
            "name": "Red Hat"
        },
        {
            "metric": 49,
            "id": "Cisco Systems",
            "name": "Cisco Systems"
        },
        {
            "metric": 46,
            "id": "*independent",
            "name": "*independent"
        }
    ]
}

2.4 Contribution by Engineers

Description

Stats on contribution per engineers. The data contains list of engineers with their metric. Engineers who has metric 0 are omitted. For reviews also added column with review distribution.

Request

Verb	URI	Description
GET	/api/1.0/stats/engineers	Contribution by Engineers

Example Request: Commits

GET /api/1.0/stats/engineers?release=havana&metric=commits&project_type=openstack&module=pbr

Example Response

{
    "stats": [
        {
            "metric": 54,
            "id": "mordred",
            "name": "Monty Taylor"
        },
        {
            "metric": 6,
            "id": "jdanjou",
            "name": "Julien Danjou"
        },
        {
            "metric": 4,
            "id": "doug-hellmann",
            "name": "Doug Hellmann"
        },
        {
            "metric": 3,
            "id": "slukjanov",
            "name": "Sergey Lukjanov"
        }
    ]
}

Example Request: Reviews

GET /api/1.0/stats/engineers?release=havana&metric=marks&project_type=openstack&module=pbr

Example Response

{
    "stats": [
        {
            "comment": "1|3|55|45 (96.2%)",
            "metric": 104,
            "id": "mordred",
            "name": "Monty Taylor"
        },
        {
            "comment": "0|13|18|51 (84.1%)",
            "metric": 82,
            "id": "cboylan",
            "name": "Clark Boylan"
        },
        {
            "comment": "0|13|11|36 (78.3%)",
            "metric": 60,
            "id": "doug-hellmann",
            "name": "Doug Hellmann"
        }
    ]
}

2.5 Activity log

Description

Depending on selected metric Activity log contains commits, reviews, emails or blueprints.

Request

Verb	URI	Description
GET	/api/1.0/activity	Activity log

When querying the activity log, the page_size and start_record parameters can be used to manage the paging of results (splitting results over multiple requests/responses). The default value of page_size is 10.

Example Response

{
    "activity": [
        {
            "record_type": "commit",
            "primary_key": "63580a7298887e6909602d8d96859b4e96b017e3",
            "commit_id": "63580a7298887e6909602d8d96859b4e96b017e3",
            "user_id": "zulcss",
            "launchpad_id": "zulcss",
            "author_name": "Chuck Short",
            "author_email": "chuck.short@canonical.com",
            "module": "ceilometer",
            "release": "havana",
            "blueprint_id": [],
            "bug_id": [],
            "date": 1370134263,
            "branches": "master",
            "message": "Introduce py33 to tox.ini to make testing with python3 easier.\n",
            "subject": "python3: Introduce py33 to tox.ini",
            "change_id": [
                "I96d1ecd3f0069295e27127239c83afc32673ffec"
            ],
            "company_name": "Canonical",
            "loc": 2,
            "files_changed": 1,
            "lines_added": 1,
            "lines_deleted": 1
        }
    ]
}

2.6 Contribution summary

Description

Get contribution summary: number of commits, locs, emails, drafted and completed blueprints, review marks with distribution per mark (-2..+2).

Request

Verb	URI	Description
GET	/api/1.0/contribution	Contribution summary

Example Response

{
    "contribution": {
        "loc": 252,
        "new_blueprint_count": 2,
        "email_count": 7,
        "commit_count": 5,
        "competed_blueprint_count": 0,
        "marks": {
            "0": 0,
            "1": 12,
            "2": 2,
            "-1": 5,
            "-2": 0
        }
    }
}