Documentation/rest-api-projects.txt

Gerrit Code Review - '/projects/' REST API
==========================================

This page describes the project related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].

Endpoints
---------

GET /projects/ (List Projects)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lists the projects accessible by the caller. This is the same as
using the link:cmd-ls-projects.html[ls-projects] command over SSH,
and accepts the same options as query parameters.

As result a map is returned that maps the project names to
link:#project-info[ProjectInfo] entries. The entries in the map are sorted
by project name.

.Request
----
  GET /projects/?d HTTP/1.0
----

.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "external/bison": {
      "kind": "gerritcodereview#project",
      "id": "external%2Fbison",
      "description": "GNU parser generator"
    },
    "external/gcc": {
      "kind": "gerritcodereview#project",
      "id": "external%2Fgcc",
    },
    "external/openssl": {
      "kind": "gerritcodereview#project",
      "id": "external%2Fopenssl",
      "description": "encryption\ncrypto routines"
    },
    "test": {
      "kind": "gerritcodereview#project",
      "id": "test",
      "description": "\u003chtml\u003e is escaped"
    }
  }
----

.Get all projects with their description
****
get::/projects/?d
****

[[suggest-projects]]
The `/projects/` URL also accepts a prefix string in the `p` parameter.
This limits the results to those projects that start with the specified
prefix.
List all projects that start with `platform/`:

.Request
----
  GET /projects/?p=platform%2F HTTP/1.0
----

.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "platform/drivers": {
      "kind": "gerritcodereview#project",
      "id": "platform%2Fdrivers",
    },
    "platform/tools": {
      "kind": "gerritcodereview#project",
      "id": "platform%2Ftools",
    }
  }
----
E.g. this feature can be used by suggestion client UI's to limit results.

GET /projects/\{project-name\}/dashboards/ (List Dashboards)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List custom dashboards for a project.

As result a list of link:#dashboard-info[DashboardInfo] entries is
returned.

List all dashboards for the `work/my-project` project:

.Request
----
  GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0
----

.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  [
    {
      "kind": "gerritcodereview#dashboard",
      "id": "main:closed",
      "ref": "main",
      "path": "closed",
      "description": "Merged and abandoned changes in last 7 weeks",
      "url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
      "default": true,
      "title": "Closed changes",
      "sections": [
        {
          "name": "Merged",
          "query": "status:merged age:7w"
        },
        {
          "name": "Abandoned",
          "query": "status:abandoned age:7w"
        }
      ]
    }
  ]
----

.Get all dashboards of the 'All-Projects' project
****
get::/projects/All-Projects/dashboards/
****

To retrieve only the default dashboard, add `default` to the URL:

.Request
----
  GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0
----

.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json;charset=UTF-8

  )]}'
  {
    "kind": "gerritcodereview#dashboard",
    "id": "main:closed",
    "ref": "main",
    "path": "closed",
    "default": true,
    ...
  }
----


[[ids]]
IDs
---

\{project-name\}
~~~~~~~~~~~~~~~~
The name of the project.


[[json-entities]]
JSON Entities
-------------

[[dashboard-info]]
DashboardInfo
~~~~~~~~~~~~~
The `DashboardInfo` entity contains information about a project
dashboard.

[options="header",width="50%",cols="1,^2,4"]
|===============================
|Field Name        ||Description
|`kind`            ||`gerritcodereview#dashboard`
|`id`              ||
The ID of the dashboard. The ID has the format '<ref>:<path>',
where ref and path are URL encoded.
|`project`         ||
The name of the project for which this dashboard is returned.
|`defining_project`||
The name of the project in which this dashboard is defined.
This is different from `project` if the dashboard is inherited from a
parent project.
|`ref`             ||
The name of the ref in which the dashboard is defined, without the
`refs/meta/dashboards/` prefix, which is common for all dashboard refs.
|`path`            ||
The path of the file in which the dashboard is defined.
|`description`     |optional|The description of the dashboard.
|`foreach`         |optional|
Subquery that applies to all sections in the dashboard. +
Tokens such as `${project}` are not resolved.
|`url`             ||
The URL under which the dashboard can be opened in the Gerrit WebUI. +
The URL is relative to the canonical web URL. +
Tokens in the queries such as `${project}` are resolved.
|`default`         |not set if `false`|
Whether this is the default dashboard of the project.
|`title`           |optional|The title of the dashboard.
|`sections`        ||
The list of link:#dashboard-section-info[sections] in the dashboard.
|===============================

[[dashboard-section-info]]
DashboardSectionInfo
~~~~~~~~~~~~~~~~~~~~
The `DashboardSectionInfo` entity contains information about a section
in a dashboard.

[options="header",width="50%",cols="1,6"]
|===========================
|Field Name    |Description
|`name`        |The title of the section.
|`query`       |The query of the section. +
Tokens such as `${project}` are not resolved.
|===========================

[[project-info]]
ProjectInfo
~~~~~~~~~~~
The `ProjectInfo` entity contains information about a project.

[options="header",width="50%",cols="1,^2,4"]
|===========================
|Field Name    ||Description
|`kind`        ||`gerritcodereview#project`
|`id`          ||The URL encoded project name.
|`name`        |
not set if returned in a map where the project name is used as map key|
The name of the project.
|`parent`      |optional, +
not set for the root project|
The name of the parent project. +
`?-<n>` if the parent project is not visible (`<n>` is a number which
is increased for each non-visible project).
|`description` |optional|The description of the project.
|`branches`    |optional|Map of branch names to HEAD revisions.
|===========================


GERRIT
------
Part of link:index.html[Gerrit Code Review]