opendev/gerrit
Code Issues Proposed changes
gerrit/Documentation/rest-api-projects.txt
Edwin Kempin 7620274657 Add anchors for the REST endpoints that have none 
Change-Id: I0f0eb7d3b74837cc83612b4dc0f5c5dd1a0663a5
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
2013-02-15 13:51:50 +01:00

582 lines
15 KiB
Plaintext
Raw Blame History

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
---------
[[project-endpoints]]
Project Endpoints
-----------------
[[list-projects]]
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-project-description]]
GET /projects/\{project-name\}/description (Get Project Description)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves the description of a project.
.Request
----
GET /projects/plugins%2Freplication/description HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"Copies to other servers using the Git protocol"
----
[[set-project-description]]
PUT /projects/\{project-name\}/description (Set Project Description)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the description of a project.
The new project description must be provided in the request body inside
a link:#project-description-input[ProjectDescriptionInput] entity.
.Request
----
PUT /projects/plugins%2Freplication/description HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"description": "Plugin for Gerrit that handles the replication.",
"commit_message": "Update the project description"
}
----
As response the new project description is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"Plugin for Gerrit that handles the replication."
----
[[delete-project-description]]
DELETE /projects/\{project-name\}/description (Delete Project Description)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deletes the description of a project.
A message to commit the change of the project description can be
specified in the request body inside a
link:#project-description-input[ProjectDescriptionInput] entity.
Please note, that some proxies prohibit request bodies for DELETE
requests. In this case, if you want to specify a commit message, use
link:#set-project-description[PUT] to delete the description.
.Request
----
DELETE /projects/plugins%2Freplication/description HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[get-project-parent]]
GET /projects/\{project-name\}/parent (Get Project Parent)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves the name of a project's parent project. For the
`All-Projects` root project an empty string is returned.
.Request
----
GET /projects/plugins%2Freplication/parent HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"All-Projects"
----
[[set-project-parent]]
PUT /projects/\{project-name\}/parent (Set Project Parent)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the parent project for a project.
The new name of the parent project must be provided in the request body
inside a link:#project-parent-input[ProjectParentInput] entity.
.Request
----
PUT /projects/plugins%2Freplication/parent HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"parent": "Public-Plugins",
"commit_message": "Update the project parent"
}
----
As response the new parent project name is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"Public-Plugins"
----
[[dashboard-endpoints]]
Dashboard Endpoints
-------------------
[[list-dashboards]]
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/
****
[[get-dashboard]]
GET /projects/\{project-name\}/dashboards/\{dashboard-id\} (Get Dashboard)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a project dashboard. The dashboard can be defined on that
project or be inherited from a parent project.
.Request
----
GET /projects/work%2Fmy-project/dashboards/main:closed HTTP/1.0
----
As response a link:#dashboard-info[DashboardInfo] entity is returned
that describes the dashboard.
.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"
}
]
}
----
To retrieve the default dashboard of a project use `default` as
dashboard-id.
.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",
"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"
}
]
}
----
[[set-dashboard]]
PUT /projects/\{project-name\}/dashboards/\{dashboard-id\} (Set Dashboard)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Updates/Creates a project dashboard.
Currently only supported for the `default` dashboard.
The creation/update information for the dashboard must be provided in
the request body as a link:#dashboard-input[DashboardInput] entity.
.Request
----
PUT /projects/work%2Fmy-project/dashboards/default HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"id": "main:closed",
"commit_message": "Define the default dashboard"
}
----
As response the new/updated dashboard is returned as a
link:#dashboard-info[DashboardInfo] entity.
.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"
}
]
}
----
[[delete-dashboard]]
DELETE /projects/\{project-name\}/dashboards/\{dashboard-id\} (Delete Dashboard)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deletes a project dashboard.
Currently only supported for the `default` dashboard.
A message to commit the deletion of the project dashboard can be
specified in the request body inside a link:#dashboard-input[
DashbaordInput] entity.
Please note that some proxies prohibit request bodies for DELETE
requests.
.Request
----
DELETE /projects/work%2Fmy-project/dashboards/default HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[ids]]
IDs
---
\{dashboard-id\}
~~~~~~~~~~~~~~~~
The ID of a dashboard in the format '<ref>:<path>'.
A special dashboard ID is `default` which represents the default
dashboard of a project.
\{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-input]]
DashboardInput
~~~~~~~~~~~~~~
The `DashboardInput` entity contains information to create/update a
project dashboard.
[options="header",width="50%",cols="1,^2,4"]
|=============================
|Field Name ||Description
|`id` |optional|
ID of a dashboard to which this dashboard should link to.
|`commit_message`|optional|
Message that should be used to commit the change of 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-description-input]]
ProjectDescriptionInput
~~~~~~~~~~~~~~~~~~~~~~~
The `ProjectDescriptionInput` entity contains information for setting a
project description.
[options="header",width="50%",cols="1,^2,4"]
|=============================
|Field Name ||Description
|`description` |optional|The project description. +
The project description will be deleted if not set.
|`commit_message`|optional|
Message that should be used to commit the change of the project
description in the `project.config` file to the `refs/meta/config`
branch.
|=============================
[[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.
|===========================
[[project-parent-input]]
ProjectParentInput
~~~~~~~~~~~~~~~~~~
The `ProjectParentInput` entity contains information for setting a
project parent.
[options="header",width="50%",cols="1,^2,4"]
|=============================
|Field Name ||Description
|`parent` ||The name of the parent project.
|`commit_message`|optional|
Message that should be used to commit the change of the project parent
in the `project.config` file to the `refs/meta/config` branch.
|=============================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
View Git Blame Copy Permalink