Added documentation on API
Implements blueprint api-docs Change-Id: I0c539c22ed36f4f2ec626a364912d7b1492df294
This commit is contained in:
Ilya Shakhat
parent
9c858cfb6a
commit
6b19d37082
@ -13,7 +13,7 @@ Overview
|
||||
* `Wiki <https://wiki.openstack.org/wiki/Stackalytics>`_
|
||||
|
||||
|
||||
User guide
|
||||
API
|
||||
----------
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@ -3,7 +3,7 @@ Stackalytics JSON API v1.0
|
||||
|
||||
.. note::
|
||||
|
||||
JSON API v1.0 corresponds to Stackalytics v0.2.X
|
||||
JSON API v1.0 corresponds to Stackalytics v0.3.X
|
||||
|
||||
1 General API information
|
||||
=========================
|
||||
@ -14,25 +14,22 @@ This section contains base info about the Stackalytics JSON API design.
|
||||
1.2 Request / Response Types
|
||||
----------------------------
|
||||
|
||||
The Stackalytics API supports the JSON data serialization format.
|
||||
This means that for requests that contain a body, the Content-Type header must be set to the MIME type value
|
||||
"application/json". Also, clients should accept JSON serialized responses by specifying the Accept header
|
||||
with the MIME type value "application/json" or adding ".json" extension to the resource name.
|
||||
The default response format is "application/json" if the client omits to specify an Accept header
|
||||
or append the ".json" extension in the URL path.
|
||||
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:
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /v1.0/data/companies.json
|
||||
GET /v1.0/data/companies
|
||||
|
||||
or
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /v1.0/data/companies
|
||||
Accept: application/json
|
||||
GET /v1.0/data/companies?callback=myCallback
|
||||
Accept: application/javascript
|
||||
|
||||
1.3 Faults
|
||||
----------
|
||||
@ -42,18 +39,305 @@ Stackalytics uses only standard HTTP error codes. 4xx errors indicate problems i
|
||||
request being sent from the client and 5xx errors indicate server-side problems.
|
||||
|
||||
|
||||
2 Metrics
|
||||
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, e.g. 'core', by default 'openstack' |
|
||||
+----------------+---------------------------------------------------------------------------+
|
||||
| module | Name of module (repository name) |
|
||||
+----------------+---------------------------------------------------------------------------+
|
||||
| company | Company name |
|
||||
+----------------+---------------------------------------------------------------------------+
|
||||
| user_id | Launchpad id of user or email if no Laucnhpad id is mapped. |
|
||||
+----------------+---------------------------------------------------------------------------+
|
||||
| metric | Metric: 'commits', 'loc', 'marks', 'emails' |
|
||||
+----------------+---------------------------------------------------------------------------+
|
||||
|
||||
2.2 Contribution by Modules
|
||||
---------------------------
|
||||
|
||||
**Description**
|
||||
|
||||
Get different metrics.
|
||||
Stats on contribution per modules. The data contains list of modules with their metric.
|
||||
Modules which metric is 0 are omitted.
|
||||
|
||||
**Plugins ops**
|
||||
**Request**
|
||||
|
||||
+-----------------+-------------------------------------------------------------------+-----------------------------------------------------+
|
||||
| Verb | URI | Description |
|
||||
+=================+===================================================================+=====================================================+
|
||||
| GET | /v1.0/data/companies | Contribution by companies. |
|
||||
| GET | /api/1.0/stats/modules | Contribution by Modules |
|
||||
+-----------------+-------------------------------------------------------------------+-----------------------------------------------------+
|
||||
|
||||
**Example Request**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /api/1.0/stats/modules?release=havana&metric=commits&project_type=openstack&user_id=zulcss
|
||||
|
||||
**Example Response**
|
||||
|
||||
.. sourcecode:: json
|
||||
|
||||
{
|
||||
"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**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /api/1.0/stats/companies?release=havana&metric=commits&project_type=openstack&module=neutron
|
||||
|
||||
**Example Response**
|
||||
|
||||
.. sourcecode:: json
|
||||
|
||||
{
|
||||
"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**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /api/1.0/stats/engineers?release=havana&metric=commits&project_type=openstack&module=pbr
|
||||
|
||||
**Example Response**
|
||||
|
||||
.. sourcecode:: json
|
||||
|
||||
{
|
||||
"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**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /api/1.0/stats/engineers?release=havana&metric=marks&project_type=openstack&module=pbr
|
||||
|
||||
|
||||
**Example Response**
|
||||
|
||||
.. sourcecode:: json
|
||||
|
||||
{
|
||||
"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 |
|
||||
+-----------------+-------------------------------------------------------------------+-----------------------------------------------------+
|
||||
|
||||
**Example Response**
|
||||
|
||||
.. sourcecode:: json
|
||||
|
||||
{
|
||||
"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**
|
||||
|
||||
.. sourcecode:: json
|
||||
|
||||
{
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user