kanbanworkflowstimelinescrumrubyroadmapproject-planningproject-managementopenprojectangularissue-trackerifcgantt-chartganttbug-trackerboardsbcf
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
196 lines
7.5 KiB
196 lines
7.5 KiB
# /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
|
|
|