stackalytics/doc/source/userdoc/api_v1.0.rst
MaoyangLiu 4c99aad368 modify http link to https link
Change-Id: Ie61efa8bcfeeafd15426c8728c741c7e7b34f553
2018-12-16 15:34:37 +08:00

12 KiB

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
        }
    }
}