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

# /api/v3/memberships/{id}
---
delete:
  parameters:
  - description: Membership id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '204':
      description: Returned if the membership was successfully deleted
      headers: {}
    '403':
      content:
        application/hal+json:
          schema:
            $ref: "../components/schemas/error_response.yml"
          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:** manage members        
      headers: {}
    '404':
      content:
        application/hal+json:
          schema:
            $ref: "../components/schemas/error_response.yml"
          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:** view members

        *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:
  - Memberships
  description: Deletes the membership.
  operationId: Delete_membership
  summary: Delete membership
get:
  parameters:
  - description: Membership id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  principal...: {}
                  project...: {}
                  roles...: []
                _links:
                  principal:
                    href: "/api/v3/users/4"
                    title: Some user
                  project:
                    href: "/api/v3/projects/3"
                    title: A project
                  roles:
                  - href: "/api/v3/roles/5"
                    title: Member
                  - href: "/api/v3/roles/4"
                    title: Reader
                  schema:
                    href: "/api/v3/memberships/schema"
                  self:
                    href: "/api/v3/memberships/11"
                    title: Some user
                  update:
                    href: "/api/v3/memberships/11/form"
                    method: post
                  updateImmediately:
                    href: "/api/v3/memberships/11"
                    method: patch
                _type: Membership
                createdAt: '2015-03-20T12:56:56Z'
                id: 11
                updatedAt: '2018-12-20T18:16:11Z'
          schema:
            "$ref": "../components/schemas/view_membership_model.yml"
      description: OK
      headers: {}
    '404':
      content:
        application/hal+json:
          schema:
            $ref: "../components/schemas/error_response.yml"
          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:** view members **or** manage members

        *Note: A client without sufficient permissions shall not be able to test for the existence of
        a membership. That's why a 404 is returned here, even if a 403 might be more appropriate.*        
      headers: {}
  tags:
  - Memberships
  description: ''
  operationId: View_membership
  summary: View membership
patch:
  parameters:
  - description: Membership id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '200':
      content:
        application/hal+json:
          schema:
            "$ref": "../components/schemas/view_membership_model.yml"
      description: OK
      headers: {}
    '400':
      content:
        application/hal+json:
          schema:
            $ref: "../components/schemas/error_response.yml"
          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:
          schema:
            $ref: "../components/schemas/error_response.yml"
          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:** Manage members in the membership's project.        
      headers: {}
    '404':
      content:
        application/hal+json:
          schema:
            $ref: "../components/schemas/error_response.yml"
          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:** view member

        *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:
          schema:
            $ref: "../components/schemas/error_response.yml"
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: roles
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Roles has an unassignable role.
      description: |-
        Returned if:

        * a constraint for a property was violated (`PropertyConstraintViolation`)        
      headers: {}
  tags:
  - Memberships
  description: |-
    Updates the given membership by applying the attributes provided in the body.

    By providing a `notificationMessage` within the `_meta` block of the payload, the client can include a customized message to the user
    of the updated membership. In case of a group, the message will be sent to every user belonging to the group.

    By including `{ "sendNotifications": false }` within the `_meta` block of the payload, no notifications is send out at all.    
  operationId: Update_membership
  summary: Update membership