From 6b19d37082981320abf898d4c19c0d7b3f43954b Mon Sep 17 00:00:00 2001 From: Ilya Shakhat Date: Sat, 21 Sep 2013 13:41:50 +0400 Subject: [PATCH] Added documentation on API Implements blueprint api-docs Change-Id: I0c539c22ed36f4f2ec626a364912d7b1492df294 --- doc/source/index.rst | 2 +- doc/source/userdoc/api_v1.0.rst | 312 ++++++++++++++++++++++++++++++-- 2 files changed, 299 insertions(+), 15 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index ca96040c1..3f084fa9a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,7 +13,7 @@ Overview * `Wiki `_ -User guide +API ---------- .. toctree:: :maxdepth: 1 diff --git a/doc/source/userdoc/api_v1.0.rst b/doc/source/userdoc/api_v1.0.rst index ef732dbc0..1c0abed93 100644 --- a/doc/source/userdoc/api_v1.0.rst +++ b/doc/source/userdoc/api_v1.0.rst @@ -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 + } + } + } +