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

# /api/v3/memberships
---
get:
  parameters:
  - description: |-
      JSON specifying filter conditions.
      Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
      Currently supported filters are:

      + any_name_attribute: filters memberships based on the name of the principal. All possible name variants (and also email and login) are searched.

      + blocked: reduces the result set to all memberships that are temporarily blocked or that are not blocked temporarily.

      + group: filters memberships based on the name of a group. The group however is not the principal used for filtering. Rather, the memberships of the group are used as the filter values.

      + name: filters memberships based on the name of the principal. Note that only the name is used which depends on a setting in the OpenProject instance.

      + principal: filters memberships based on the id of the principal.

      + project: filters memberships based on the id of the project.

      + role: filters memberships based on the id of any role assigned to the membership.

      + status: filters memberships based on the status of the principal.

      + created_at: filters memberships based on the time the membership was created.

      + updated_at: filters memberships based on the time the membership was updated last.
    examples:
      name-filter:
        summary: Filtering on the name of the principal
        value: '[{ "name": { "operator": "=", "values": ["A User"] }" }]'
      global-memberships:
        summary: Get memberships for global roles
        value: '[{ "project": { "operator": "!*", "values": null }" }]'
    in: query
    name: filters
    required: false
    schema:
      type: string
  - description: |-
      JSON specifying sort criteria.
      Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

      + id: Sort by primary key

      + name: Sort by the name of the principal. Note that this depends on the setting for how the name is to be displayed at least for users.

      + email: Sort by the email address of the principal. Groups and principal users, which do not have an email, are sorted last.

      + status: Sort by the status of the principal. Groups and principal users, which do not have a status, are sorted together with the active users.

      + created_at: Sort by membership creation datetime

      + updated_at: Sort by the time the membership was updated last
    example: '[["id", "asc"]]'
    in: query
    name: sortBy
    required: false
    schema:
      default: '[["id", "asc"]]'
      type: string
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  elements:
                  - _links:
                      principal:
                        href: "/api/v3/users/5"
                        title: A user
                      project:
                        href: "/api/v3/projects/3"
                        title: A Project
                      roles:
                      - href: "/api/v3/roles/4"
                        title: Reader
                      schema:
                        href: "/api/v3/memberships/schema"
                      self:
                        href: "/api/v3/memberships/11"
                    _type: Membership
                    createdAt: '2015-03-20T12:56:56Z'
                    id: 11
                    updatedAt: '2018-12-20T18:16:11Z'
                  - _links:
                      principal:
                        href: "/api/v3/groups/5"
                        title: A group
                      project:
                        href: "/api/v3/projects/6"
                        title: Another Project
                      roles:
                      - href: "/api/v3/roles/8"
                        title: Project admin
                      schema:
                        href: "/api/v3/memberships/schema"
                      self:
                        href: "/api/v3/memberships/41"
                    _type: Membership
                    createdAt: '2019-12-22T12:56:06Z'
                    id: 41
                    updatedAt: '2020-12-20T18:16:12Z'
                _links:
                  self:
                    href: "/api/v3/memberships"
                _type: Collection
                count: 2
                total: 2
          schema:
            "$ref": "../components/schemas/list_memberships_model.yml"
      description: OK
      headers: {}
  tags:
  - Memberships
  description: Returns a collection of memberships. The client can choose to filter
    the memberships similar to how work packages are filtered. In addition to the
    provided filters, the server will reduce the result set to only contain memberships,
    for which the requesting client has sufficient permissions (*view_members*, *manage_members*).
  operationId: List_memberships
  summary: List memberships
post:
  responses:
    '201':
      content:
        application/hal+json:
          schema:
            "$ref": "../components/schemas/view_membership_model.yml"
      description: Created
      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
      headers: {}
    '422':
      content:
        application/hal+json:
          schema:
            $ref: "../components/schemas/error_response.yml"
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: project
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Project can't be blank.
      description: |-
        Returned if:

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

    You can use the form and schema to retrieve the valid attribute values and by that be guided towards successful creation.

    By providing a `notificationMessage` within the `_meta` block of the payload, the client can include a customized message to the user
    of the newly created 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: Create_membership
  summary: Create membership