openproject/docs/api/apiv3/paths/group.yml

# /api/v3/groups/{id}
---
delete:
  parameters:
  - description: Group id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '202':
      description: |-
        Returned if the group was successfully deleted

        Note that the response body is empty as of now. In future versions of the API a body
        *might* be returned, indicating the progress of deletion.
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** Administrator
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
      description: |-
        Returned if the group does not exist or the client does not have sufficient permissions
        to see it.

        **Required permission:** Administrator

        *Note: A client without sufficient permissions shall not be able to test for the existence of
        a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
      headers: {}
  tags:
  - Groups
  description: Deletes the group.
  operationId: Delete_group
  summary: Delete group
get:
  parameters:
  - description: Group id.
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _links:
                  delete:
                    href: "/api/v3/group/9"
                    method: delete
                  members:
                  - href: "/api/v3/users/363"
                    title: First user
                  - href: "/api/v3/users/60"
                    title: Second user
                  memberships:
                    href: /api/v3/memberships?filters=[{"principal":{"operator":"=","values":["9"]}}]
                    title: Memberships
                  self:
                    href: "/api/v3/groups/9"
                    title: The group
                  updateImmediately:
                    href: "/api/v3/group/9"
                    method: patch
                _type: Group
                createdAt: '2015-09-23T11:06:36Z'
                id: 9
                name: The group
                updatedAt: '2015-09-23T11:06:36Z'
          schema:
            "$ref": "../components/schemas/view_group_model.yml"
      description: OK
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
      description: |-
        Returned if the group does not exist or if the API user does not have permission to view them.

        **Required permission** If the user has the *manage members* permission in at least one project the user will be able to query all groups. If not, the user
        will be able to query all groups which are members in projects, he has the *view members* permission in.
      headers: {}
  tags:
  - Groups
  description: ''
  operationId: View_group
  summary: View group
patch:
  parameters:
  - description: Group id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '200':
      content:
        application/hal+json:
          schema:
            "$ref": "../components/schemas/view_group_model.yml"
      description: OK
      headers: {}
    '400':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request body was not a single JSON object.
      description: Occurs when the client did not send a valid JSON object in the
        request body.
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** Administrator
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
      description: |-
        Returned if the membership does not exist or the client does not have sufficient permissions
        to see it.

        **Required permission** If the user has the *manage members* permission in at least one project the user will be able to query all groups. If not, the user
        will be able to query all groups which are members in projects, he has the *view members* permission in.

        *Note: A client without sufficient permissions shall not be able to test for the existence of
        a version. That's why a 404 is returned here, even if a 403 might be more appropriate.*
      headers: {}
    '422':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: members
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Member is already taken.
      description: |-
        Returned if:

        * a constraint for a property was violated (`PropertyConstraintViolation`)
      headers: {}
  tags:
  - Groups
  description: Updates the given group by applying the attributes provided in the
    body.
  operationId: Update_group
  summary: Update group