groups.asc #1

=== Helix Versioning Engine Groups

[[get_p4_vX_groups]]
==== `GET /p4/v[api]/groups`
    
Lists available groups in the system.
The resources of this list are summaries of groups in the system.

===== Request URL Path Parameters

[cols="2*", options="header"]
|===
| Parameter
| Description

| `api`
| The Helix Versioning Engine API level.
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Response Body JSON

See <<error_responses>> for the format of failures.

The values of this method are based on the result of the http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_groups.html[`p4 -ztag groups`] command.
The output of this command is quite a bit different from typical listing queries.

For example, here's a listing that includes one group with two users:

[source,json]
----
[
  {
    "user": "mmustermann",
    "group": "test_MUFFUMMY",
    "isSubGroup": "0",
    "isOwner": "0",
    "isUser": "1",
    "maxResults": "0",
    "maxScanRows": "0",
    "maxLockTime": "0",
    "timeout": "43200",
    "passTimeout": "0"
  },
  {
    "user": "super",
    "group": "test_MUFFUMMY",
    "isSubGroup": "0",
    "isOwner": "0",
    "isUser": "1",
    "maxResults": "0",
    "maxScanRows": "0",
    "maxLockTime": "0",
    "timeout": "43200",
    "passTimeout": "0"
  }
]
----

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#groups-instance_method[`HelixWebServicesClient#groups`]




[[post_p4_vX_groups]]
==== `POST /p4/v[api]/groups`
    
Creates a new group specification, like the `p4 group` command.

There are no other parameters to this method.

===== Request URL Path Parameters

[cols="2*", options="header"]
|===
| Parameter
| Description

| `api`
| The Helix Versioning Engine API level.
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Request Body JSON

Properties of the JSON object are the form fields of the http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_group.html[p4 group] command.

For example:

[source,json]
----
{
  "Group": "new_group_id",
  "Users": ["jdoe", "mmustermann"]
}
----

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#create_group-instance_method[`HelixWebServicesClient#create_group`]




[[get_p4_vX_groups_group]]
==== `GET /p4/v[api]/groups/[group]`

Return group details, similar to the `p4 group -o` command.

===== Request URL Path Parameters

[cols="2*", options="header"]
|===
| Parameter
| Description

| `api`
| The Helix Versioning Engine API level.

| group
| The group name.
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Response Data

Returns the form fields of the http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_group.html[`p4 -ztag group [group name]`] command.
For more information, see the command reference.

Please note that the way 'unset' is described in this output is different from the listing data.

[source,json]
----
{
  "Group": "test_MUFFUMMY",
  "MaxResults": "unset",
  "MaxScanRows": "unset",
  "MaxLockTime": "unset",
  "Timeout": "43200",
  "PasswordTimeout": "unset",
  "Users": [
    "mmustermann",
    "super"
  ]
}
----

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#group-instance_method[`HelixWebServicesClient#group`]




[[patch_p4_vX_groups_group]]
==== `PATCH /p4/v[api]/groups/[group]`

Update group specifications, similar to the `p4 group` command.
Only the specified parameters in the body will be changed.

===== Request URL Path Parameters

[cols="2*", options="header"]
|===
| Parameter
| Description

| `api`
| The Helix Versioning Engine API level.

| group
| The name of the group
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Request Body JSON

A single JSON object containing form fields of the http://www.perforce.com/perforce/doc.current/manuals/cmdref/p4_group.html[`p4 -ztag group [group name]`] command.

An example updating the list of users:

[source,json]
----
{
  "Users": ["jdoe", "mmustermann", "saustin"]
}
----

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#update_group-instance_method[`HelixWebServicesClient#update_group`]




[[delete_p4_vX_groups_group]]
===== `DELETE /p4/v[api]/groups/[group]`
    
Removes the group specification, similar to the `p4 group -d` command.

===== Request URL Path Parameters

[cols="2*", options="header"]
|===
| Parameter
| Description

| `api`
| The Helix Versioning Engine API level.

| group
| The name of the group
|===

===== Request Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Authorization`
| See <<authentication>>

| `Accept`
| `application/json`

| `Content-Type`
| `application/json`

| `X-Perforce-Helix_Web_Services-*`
| See <<per_request_configuration>>
|===

===== Response Headers

[cols="2*", options="header"]
|===
| Header Name
| Notes

| `Content-Type`
| `application/json`
|===

===== Ruby Client

See link:./helix_web_services_client_ruby/HelixWebServicesClient.html#delete_group-instance_method[`HelixWebServicesClient#delete_group`]