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" ---- If the project does not have a description an empty string is returned. [[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." ---- If the description was deleted the response is "`204 No Content`". [[delete-project-description]] DELETE /projects/\{project-name\}/description (Delete Project Description) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Deletes the description of a project. The request body does not need to include a link:#project-description-input[ProjectDescriptionInput] entity if no commit message is specified. 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. The request body does not need to include a link:#dashboard-input[ DashbaordInput] entity if no commit message is specified. 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 ':'. 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 ':', 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. + `?-` if the parent project is not visible (`` 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]