Skip to content

Commit 87f4e86

Browse files
heiytorheiytor
committed
docs(openapi): add new membership-invitations routes
1 parent f5536fd commit 87f4e86

9 files changed

Lines changed: 289 additions & 21 deletions

‎openapi/spec/cloud-openapi.yaml‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -112,12 +112,20 @@ paths:
112112
$ref: paths/api@connector@{uid}.yaml
113113
/api/connector/{uid}/info:
114114
$ref: paths/api@connector@{uid}@info.yaml
115-
/api/namespaces/{tenant}/members/accept-invite:
116-
$ref: paths/api@namespaces@{tenant}@members@accept-invite.yaml
117-
/api/namespaces/{tenant}/members/invites:
118-
$ref: paths/api@namespaces@{tenant}@members@invites.yaml
115+
/api/namespaces/{tenant}/invitations/links:
116+
$ref: paths/api@namespaces@{tenant}@invitations@links.yaml
119117
/api/namespaces/{tenant}/members/{id}/accept-invite:
120118
$ref: paths/api@namespaces@{tenant}@members@{id}@accept-invite.yaml
119+
/api/namespaces/{tenant}/invitations/accept:
120+
$ref: paths/api@namespaces@{tenant}@invitations@accept.yaml
121+
/api/namespaces/{tenant}/invitations/decline:
122+
$ref: paths/api@namespaces@{tenant}@invitations@decline.yaml
123+
/api/namespaces/{tenant}/invitations/{user-id}:
124+
$ref: paths/api@namespaces@{tenant}@invitations@{user-id}.yaml
125+
/api/namespaces/{tenant}/invitations:
126+
$ref: paths/api@namespaces@{tenant}@invitations.yaml
127+
/api/users/invitations:
128+
$ref: paths/api@users@invitations.yaml
121129
/api/namespaces/{tenant}/support:
122130
$ref: paths/api@namespaces@{tenant}@support.yaml
123131
/api/web-endpoints:

‎openapi/spec/components/schemas/membershipInvitation.yaml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
type: object
2+
description: A membership invitation to a namespace
3+
properties:
4+
namespace:
5+
type: object
6+
description: The namespace associated with this invitation
7+
properties:
8+
tenant_id:
9+
description: The namespace tenant ID
10+
type: string
11+
example: "00000000-0000-4000-0000-000000000000"
12+
name:
13+
description: The namespace name
14+
type: string
15+
example: "my-namespace"
16+
required:
17+
- tenant_id
18+
- name
19+
user:
20+
type: object
21+
description: The invited user
22+
properties:
23+
id:
24+
description: The ID of the invited user
25+
type: string
26+
example: "507f1f77bcf86cd799439011"
27+
email:
28+
description: The email of the invited user
29+
type: string
30+
example: "user@example.com"
31+
required:
32+
- id
33+
- email
34+
invited_by:
35+
description: The ID of the user who sent the invitation
36+
type: string
37+
example: "507f1f77bcf86cd799439012"
38+
created_at:
39+
description: When the invitation was created
40+
type: string
41+
format: date-time
42+
updated_at:
43+
description: When the invitation was last updated
44+
type: string
45+
format: date-time
46+
expires_at:
47+
description: When the invitation expires
48+
type: string
49+
format: date-time
50+
nullable: true
51+
status:
52+
description: The current status of the invitation
53+
type: string
54+
enum:
55+
- pending
56+
- accepted
57+
- rejected
58+
- cancelled
59+
example: pending
60+
status_updated_at:
61+
description: When the status was last updated
62+
type: string
63+
format: date-time
64+
role:
65+
$ref: ./namespaceMemberRole.yaml

‎openapi/spec/openapi.yaml‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -231,12 +231,22 @@ paths:
231231
$ref: paths/api@connector@{uid}.yaml
232232
/api/connector/{uid}/info:
233233
$ref: paths/api@connector@{uid}@info.yaml
234-
/api/namespaces/{tenant}/members/accept-invite:
235-
$ref: paths/api@namespaces@{tenant}@members@accept-invite.yaml
236-
/api/namespaces/{tenant}/members/invites:
237-
$ref: paths/api@namespaces@{tenant}@members@invites.yaml
234+
# Lookup user status
235+
# TODO: rename this endpoint
238236
/api/namespaces/{tenant}/members/{id}/accept-invite:
239237
$ref: paths/api@namespaces@{tenant}@members@{id}@accept-invite.yaml
238+
/api/namespaces/{tenant}/invitations/links:
239+
$ref: paths/api@namespaces@{tenant}@invitations@links.yaml
240+
/api/namespaces/{tenant}/invitations/accept:
241+
$ref: paths/api@namespaces@{tenant}@invitations@accept.yaml
242+
/api/namespaces/{tenant}/invitations/decline:
243+
$ref: paths/api@namespaces@{tenant}@invitations@decline.yaml
244+
/api/namespaces/{tenant}/invitations/{user-id}:
245+
$ref: paths/api@namespaces@{tenant}@invitations@{user-id}.yaml
246+
/api/namespaces/{tenant}/invitations:
247+
$ref: paths/api@namespaces@{tenant}@invitations.yaml
248+
/api/users/invitations:
249+
$ref: paths/api@users@invitations.yaml
240250
/api/namespaces/{tenant}/support:
241251
$ref: paths/api@namespaces@{tenant}@support.yaml
242252
/api/web-endpoints:

‎openapi/spec/paths/api@namespaces@{tenant}@invitations.yaml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
get:
2+
operationId: getNamespaceMembershipInvitationList
3+
summary: Get membership invitations for a namespace
4+
description: |
5+
Returns a paginated list of membership invitations for the specified namespace.
6+
This endpoint allows namespace administrators to view all pending invitations.
7+
tags:
8+
- cloud
9+
- members
10+
- namespaces
11+
security:
12+
- jwt: []
13+
parameters:
14+
- $ref: ../components/parameters/path/namespaceTenantIDPath.yaml
15+
- name: filter
16+
description: |
17+
Membership invitations filter.
18+
19+
Filter field receives a base64 encoded JSON object to limit the search.
20+
schema:
21+
type: string
22+
required: false
23+
in: query
24+
- $ref: ../components/parameters/query/pageQuery.yaml
25+
- $ref: ../components/parameters/query/perPageQuery.yaml
26+
responses:
27+
'200':
28+
description: Successfully retrieved namespace membership invitations list.
29+
headers:
30+
X-Total-Count:
31+
description: Total number of membership invitations.
32+
schema:
33+
type: integer
34+
minimum: 0
35+
content:
36+
application/json:
37+
schema:
38+
type: array
39+
items:
40+
$ref: ../components/schemas/membershipInvitation.yaml
41+
'401':
42+
$ref: ../components/responses/401.yaml
43+
'403':
44+
$ref: ../components/responses/403.yaml
45+
'404':
46+
$ref: ../components/responses/404.yaml
47+
'500':
48+
$ref: ../components/responses/500.yaml

openapi/spec/paths/api@namespaces@{tenant}@members@accept-invite.yaml renamed to openapi/spec/paths/api@namespaces@{tenant}@invitations@accept.yaml

Lines changed: 1 addition & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ patch:
22
operationId: acceptInvite
33
summary: Accept a membership invite
44
description: |
5-
This route is intended to be accessed directly through the link sent in the invitation email.
5+
Accepts a pending membership invitation for the authenticated user.
66
The user must be logged into the account that was invited.
77
tags:
88
- cloud
@@ -13,18 +13,6 @@ patch:
1313
- jwt: []
1414
parameters:
1515
- $ref: ../components/parameters/path/namespaceTenantIDPath.yaml
16-
requestBody:
17-
content:
18-
application/json:
19-
schema:
20-
type: object
21-
properties:
22-
sig:
23-
description: The unique key included in the email link.
24-
type: string
25-
example: b25e93bc-22ac-4f02-901a-52af9f358a5d
26-
required:
27-
- sig
2816
responses:
2917
'200':
3018
description: Invitation successfully accepted

‎openapi/spec/paths/api@namespaces@{tenant}@invitations@decline.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
patch:
2+
operationId: declineInvite
3+
summary: Decline a membership invite
4+
description: |
5+
Declines a pending membership invitation for the authenticated user.
6+
The user must be logged into the account that was invited.
7+
The invitation status will be updated to "rejected".
8+
tags:
9+
- cloud
10+
- members
11+
- namespaces
12+
- users
13+
security:
14+
- jwt: []
15+
parameters:
16+
- $ref: ../components/parameters/path/namespaceTenantIDPath.yaml
17+
responses:
18+
'200':
19+
description: Invitation successfully declined
20+
'400':
21+
$ref: ../components/responses/400.yaml
22+
'401':
23+
$ref: ../components/responses/401.yaml
24+
'403':
25+
$ref: ../components/responses/403.yaml
26+
'404':
27+
$ref: ../components/responses/404.yaml
28+
'500':
29+
$ref: ../components/responses/500.yaml

openapi/spec/paths/api@namespaces@{tenant}@members@invites.yaml renamed to openapi/spec/paths/api@namespaces@{tenant}@invitations@links.yaml

File renamed without changes.

‎openapi/spec/paths/api@namespaces@{tenant}@invitations@{user-id}.yaml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
patch:
2+
operationId: updateMembershipInvitation
3+
summary: Update a pending membership invitation
4+
description: |
5+
Allows namespace administrators to update a pending membership invitation.
6+
Currently supports updating the role assigned to the invitation.
7+
The active user must have authority over the role being assigned.
8+
tags:
9+
- cloud
10+
- members
11+
- namespaces
12+
security:
13+
- jwt: []
14+
parameters:
15+
- $ref: ../components/parameters/path/namespaceTenantIDPath.yaml
16+
- name: user-id
17+
description: The ID of the invited user
18+
schema:
19+
type: string
20+
required: true
21+
in: path
22+
requestBody:
23+
content:
24+
application/json:
25+
schema:
26+
type: object
27+
properties:
28+
role:
29+
$ref: ../components/schemas/namespaceMemberRole.yaml
30+
responses:
31+
'200':
32+
description: Invitation successfully updated
33+
'400':
34+
$ref: ../components/responses/400.yaml
35+
'401':
36+
$ref: ../components/responses/401.yaml
37+
'403':
38+
$ref: ../components/responses/403.yaml
39+
'404':
40+
$ref: ../components/responses/404.yaml
41+
'500':
42+
$ref: ../components/responses/500.yaml
43+
44+
delete:
45+
operationId: cancelMembershipInvitation
46+
summary: Cancel a pending membership invitation
47+
description: |
48+
Allows namespace administrators to cancel a pending membership invitation.
49+
The invitation status will be updated to "cancelled".
50+
The active user must have authority over the role of the invitation being cancelled.
51+
tags:
52+
- cloud
53+
- members
54+
- namespaces
55+
security:
56+
- jwt: []
57+
parameters:
58+
- $ref: ../components/parameters/path/namespaceTenantIDPath.yaml
59+
- name: user-id
60+
description: The ID of the invited user
61+
schema:
62+
type: string
63+
required: true
64+
in: path
65+
responses:
66+
'200':
67+
description: Invitation successfully cancelled
68+
'400':
69+
$ref: ../components/responses/400.yaml
70+
'401':
71+
$ref: ../components/responses/401.yaml
72+
'403':
73+
$ref: ../components/responses/403.yaml
74+
'404':
75+
$ref: ../components/responses/404.yaml
76+
'500':
77+
$ref: ../components/responses/500.yaml

‎openapi/spec/paths/api@users@invitations.yaml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
get:
2+
operationId: getMembershipInvitationList
3+
summary: Get membership invitations for the authenticated user
4+
description: |
5+
Returns a paginated list of membership invitations for the authenticated user.
6+
This endpoint allows users to view all namespace invitations they have received.
7+
tags:
8+
- cloud
9+
- members
10+
- namespaces
11+
security:
12+
- jwt: []
13+
parameters:
14+
- name: filter
15+
description: |
16+
Membership invitations filter.
17+
18+
Filter field receives a base64 encoded JSON object to limit the search.
19+
schema:
20+
type: string
21+
required: false
22+
in: query
23+
- $ref: ../components/parameters/query/pageQuery.yaml
24+
- $ref: ../components/parameters/query/perPageQuery.yaml
25+
responses:
26+
'200':
27+
description: Successfully retrieved membership invitations list.
28+
headers:
29+
X-Total-Count:
30+
description: Total number of membership invitations.
31+
schema:
32+
type: integer
33+
minimum: 0
34+
content:
35+
application/json:
36+
schema:
37+
type: array
38+
items:
39+
$ref: ../components/schemas/membershipInvitation.yaml
40+
'401':
41+
$ref: ../components/responses/401.yaml
42+
'500':
43+
$ref: ../components/responses/500.yaml

0 commit comments

Comments
 (0)