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.

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

 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/`:
----
 GET /projects/?p=platform%2F HTTP/1.0

 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/*/dashboards/ (List Dashboards)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List custom dashboards for a project.

The `/projects/{name}/dashboards/` URL expects the a URL encoded
project name as part of the URL. If name contains / the correct
encoding is to use `%2F`.

List all dashboards for the `work/my-project` project:
----
 GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0

 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:
----
 GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0

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

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

[[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]