gerrit/Documentation/rest-api-access.txt
Han-Wen Nienhuys e2258f6ee8 Add a groups map ProjectAccessInfo.
This lets the access UI in PolyGerrit show group names without doing
many roundtrips to discover the names.

Change-Id: Iaeb652776c80401d115038dd4abdb0342bfc47d7
2017-08-30 16:58:00 +02:00

418 lines
12 KiB
Plaintext

= Gerrit Code Review - /access/ REST API
This page describes the access rights related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].
[[access-endpoints]]
== Access Rights Endpoints
[[list-access]]
=== List Access Rights
--
'GET /access/?project=link:rest-api-projects.html#project-name[\{project-name\}]'
--
Lists the access rights for projects. The projects for which the access
rights should be returned must be specified as `project` options. The
`project` can be specified multiple times.
As result a map is returned that maps the project name to
link:#project-access-info[ProjectAccessInfo] entities.
The entries in the map are sorted by project name.
.Request
----
GET /access/?project=MyProject&project=All-Projects HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"All-Projects": {
"revision": "edd453d18e08640e67a8c9a150cec998ed0ac9aa",
"local": {
"GLOBAL_CAPABILITIES": {
"permissions": {
"priority": {
"rules": {
"15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
"action": "BATCH"
}
}
},
"streamEvents": {
"rules": {
"15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
"action": "ALLOW"
}
}
},
"administrateServer": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
}
}
}
}
},
"refs/meta/config": {
"permissions": {
"submit": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"label-Code-Review": {
"label": "Code-Review",
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW",
"min": -2,
"max": 2
},
"global:Project-Owners": {
"action": "ALLOW",
"min": -2,
"max": 2
}
}
},
"read": {
"exclusive": true,
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"push": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
}
}
},
"refs/for/refs/*": {
"permissions": {
"pushMerge": {
"rules": {
"global:Registered-Users": {
"action": "ALLOW"
}
}
},
"push": {
"rules": {
"global:Registered-Users": {
"action": "ALLOW"
}
}
}
}
},
"refs/tags/*": {
"permissions": {
"createSignedTag": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"createTag": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
}
}
},
"refs/heads/*": {
"permissions": {
"forgeCommitter": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"forgeAuthor": {
"rules": {
"global:Registered-Users": {
"action": "ALLOW"
}
}
},
"submit": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"editTopicName": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW",
"force": true
},
"global:Project-Owners": {
"action": "ALLOW",
"force": true
}
}
},
"label-Code-Review": {
"label": "Code-Review",
"rules": {
"global:Registered-Users": {
"action": "ALLOW",
"min": -1,
"max": 1
},
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW",
"min": -2,
"max": 2
},
"global:Project-Owners": {
"action": "ALLOW",
"min": -2,
"max": 2
}
}
},
"create": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
},
"push": {
"rules": {
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
},
"global:Project-Owners": {
"action": "ALLOW"
}
}
}
}
},
"refs/*": {
"permissions": {
"read": {
"rules": {
"global:Anonymous-Users": {
"action": "ALLOW"
},
"53a4f647a89ea57992571187d8025f830625192a": {
"action": "ALLOW"
}
}
}
}
}
},
"is_owner": true,
"owner_of": [
"GLOBAL_CAPABILITIES",
"refs/meta/config",
"refs/for/refs/*",
"refs/tags/*",
"refs/heads/*",
"refs/*"
],
"can_upload": true,
"can_add": true,
"config_visible": true,
"groups": {
"53a4f647a89ea57992571187d8025f830625192a": {
"url": "#/admin/groups/uuid-53a4f647a89ea57992571187d8025f830625192a",
"options": {},
"description": "Gerrit Site Administrators",
"group_id": 1,
"owner": "Administrators",
"owner_id": "53a4f647a89ea57992571187d8025f830625192a",
"created_on": "2009-06-08 23:31:00.000000000",
"name": "Administrators"
},
"global:Registered-Users": {
"options": {},
"name": "Registered Users"
},
"global:Project-Owners": {
"options": {},
"name": "Project Owners"
},
"15bfcd8a6de1a69c50b30cedcdcc951c15703152": {
"url": "#/admin/groups/uuid-15bfcd8a6de1a69c50b30cedcdcc951c15703152",
"options": {},
"description": "Users who perform batch actions on Gerrit",
"group_id": 2,
"owner": "Administrators",
"owner_id": "53a4f647a89ea57992571187d8025f830625192a",
"created_on": "2009-06-08 23:31:00.000000000",
"name": "Non-Interactive Users"
},
"global:Anonymous-Users": {
"options": {},
"name": "Anonymous Users"
}
}
},
"MyProject": {
"revision": "61157ed63e14d261b6dca40650472a9b0bd88474",
"inherits_from": {
"id": "All-Projects",
"name": "All-Projects",
"description": "Access inherited by all other projects."
},
"local": {},
"is_owner": true,
"owner_of": [
"refs/*"
],
"can_upload": true,
"can_add": true,
"config_visible": true
}
}
----
[[json-entities]]
== JSON Entities
[[access-section-info]]
=== AccessSectionInfo
The `AccessSectionInfo` describes the access rights that are assigned
on a ref.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`permissions` ||
The permissions assigned on the ref of this access section as a map
that maps the permission names to link:#permission-info[PermissionInfo]
entities.
|==================================
[[permission-info]]
=== PermissionInfo
The `PermissionInfo` entity contains information about an assigned
permission.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`label` |optional|
The name of the label. Not set if it's not a label permission.
|`exclusive` |not set if `false`|
Whether this permission is assigned exclusively.
|`rules` ||
The rules assigned for this permission as a map that maps the UUIDs of
the groups for which the permission are assigned to
link:#permission-info[PermissionRuleInfo] entities.
|==================================
[[permission-rule-info]]
=== PermissionRuleInfo
The `PermissionRuleInfo` entity contains information about a permission
rule that is assigned to group.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`action` ||
The action of this rule. For normal permissions this can be `ALLOW`,
`DENY` or `BLOCK`. Special values for global capabilities are
`INTERACTIVE` and `BATCH`.
|`force` |not set if `false`|
Whether the force flag is set.
|`min` |
not set if range is empty (from `0` to `0`) or not set|
The min value of the permission range.
|`max` |
not set if range is empty (from `0` to `0`) or not set|
The max value of the permission range.
|==================================
[[project-access-info]]
=== ProjectAccessInfo
The `ProjectAccessInfo` entity contains information about the access
rights for a project.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`revision` ||
The revision of the `refs/meta/config` branch from which the access
rights were loaded.
|`inherits_from` |not set for the `All-Project` project|
The parent project from which permissions are inherited as a
link:rest-api-projects.html#project-info[ProjectInfo] entity.
|`local` ||
The local access rights of the project as a map that maps the refs to
link:#access-section-info[AccessSectionInfo] entities.
|`is_owner` |not set if `false`|
Whether the calling user owns this project.
|`owner_of` ||The list of refs owned by the calling user.
|`can_upload` |not set if `false`|
Whether the calling user can upload to any ref.
|`can_add` |not set if `false`|
Whether the calling user can add any ref.
|`config_visible` |not set if `false`|
Whether the calling user can see the `refs/meta/config` branch of the
project.
|`groups` |A map of group UUID to
link:rest-api-groups.html#group-info[GroupInfo] objects, describing
the group UUIDs used in the `local` map. Groups that are not visible
are omitted from the `groups` map.
|==================================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------