[#41299] Updated API spec for placeholder users

config/locales/en.yml

@@ -2025,6 +2025,7 @@ en:
   label_member_new: "New member"
   label_member_all_admin: "(All roles due to admin status)"
   label_member_plural: "Members"
+  label_membership_plural: "Memberships"
   lable_membership_added: "Member added"
   lable_membership_updated: "Member updated"
   label_menu_badge:

docs/api/apiv3/components/examples/group-response.yml

@@ -0,0 +1,42 @@
+# Example: GroupResponse
+---
+value:
+  _type: Group
+  id: 26
+  name: Force Users
+  createdAt: '2024-01-11T15:54:16.542Z'
+  updatedAt: '2024-01-11T15:58:02.237Z'
+  _embedded:
+    members:
+      - _hint: Principal resource shortened for brevity
+        _type: User
+        id: 23
+        name: Grogu Jarin
+      - _hint: Principal resource shortened for brevity
+        _type: User
+        id: 14
+        name: Mara Jade
+      - _hint: Principal resource shortened for brevity
+        _type: User
+        id: 3
+        name: Darth Vader
+  _links:
+    self:
+      href: '/api/v3/groups/26'
+      title: Force Users
+    memberships:
+      href: '/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2226%22%5D%7D%7D%5D'
+      title: Memberships
+    delete:
+      href: '/api/v3/groups/26'
+      method: delete
+    updateImmediately:
+      href: '/api/v3/groups/26'
+      method: patch
+    members:
+      - href: '/api/v3/users/23'
+        title: Grogu Jarin
+      - href: '/api/v3/users/14'
+        title: Mara Jade
+      - href: '/api/v3/users/3'
+        title: Darth Vader

docs/api/apiv3/components/examples/placeholder-user-response.yml

@@ -0,0 +1,26 @@
+# Example: PlaceholderUserResponse
+---
+value:
+  _type: PlaceholderUser
+  id: 27
+  name: Akolyth
+  createdAt: '2024-02-12T11:52:24.708Z'
+  updatedAt: '2024-02-12T11:52:24.708Z'
+  _links:
+    self:
+      href: '/api/v3/placeholder_users/27'
+      title: Akolyth
+    memberships:
+      href: '/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2227%22%5D%7D%7D%5D'
+      title: Memberships
+    updateImmediately:
+      href: '/api/v3/placeholder_users/27'
+      title: Update Akolyth
+      method: patch
+    delete:
+      href: '/api/v3/placeholder_users/27'
+      title: Delete Akolyth
+      method: delete
+    showUser:
+      href: '/placeholder_users/27'
+      type: text/html

docs/api/apiv3/components/examples/user-response.yml

@@ -0,0 +1,39 @@
+# Example: UserResponse
+---
+value:
+  _type: User
+  id: 14
+  name: Mara Jade
+  createdAt: '2022-04-04T08:07:22.910Z'
+  updatedAt: '2024-02-09T09:01:17.382Z'
+  login: member
+  admin: false
+  firstName: Mara
+  lastName: Jade
+  email: [email protected]
+  avatar: 'https://secure.gravatar.com/avatar/17dd23570f3bd129d06db9b48b7a41b8?default=404&secure=true'
+  status: active
+  identityUrl: null
+  language: en
+  _links:
+    self:
+      href: '/api/v3/users/14'
+      title: Mara Jade
+    memberships:
+      href: '/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2214%22%5D%7D%7D%5D'
+      title: Memberships
+    showUser:
+      href: '/users/14'
+      type: text/html
+    updateImmediately:
+      href: '/api/v3/users/14'
+      title: Update member
+      method: patch
+    lock:
+      href: '/api/v3/users/14/lock'
+      title: Set lock on member
+      method: post
+    delete:
+      href: '/api/v3/users/14'
+      title: Delete member
+      method: delete

docs/api/apiv3/components/schemas/group_collection_model.yml

@@ -14,11 +14,11 @@ allOf:
         properties:
           self:
             allOf:
-              - $ref: "./link.yml"
+              - $ref:  './link.yml'
               - description: |-
                   This group collection
 
-                  **Resource**: GroupCollectionReadModel
+                  **Resource**: Collection
       _embedded:
         type: object
         required:

docs/api/apiv3/components/schemas/group_model.yml

@@ -1,107 +1,57 @@
 # Schema: GroupModel
 ---
-type: object
-required:
-  - _type
-  - id
-  - _links
-properties:
-  id:
-    type: integer
-    description: The group id
-    minimum: 1
-  name:
-    type: string
-    description: |-
-      Group's full name, formatting depends on instance settings
-
-      # Conditions
-      - admin
-  createdAt:
-    type: string
-    format: date-time
-    description: |-
-      Time of creation
-
-      # Conditions
-      - admin
-  updatedAt:
-    type: string
-    format: date-time
-    description: Time of the most recent change to the user
-  _links:
-    type: object
+allOf:
+  - $ref: './principal_model.yml'
+  - type: object
     required:
-      - self
+      - _type
+      - _embedded
     properties:
-      self:
-        allOf:
-          - $ref: './link.yml'
-          - description: |-
-              This group resource
-
-              **Resource**: Group
-      delete:
-        allOf:
-          - $ref: './link.yml'
-          - description: |-
-              Deletes the group.
-
-              # Conditions
-              **Permission**: Administrator
-      updateImmediately:
-        allOf:
-          - $ref: './link.yml'
-          - description: |-
-              Updates the group's attributes.
-
-              # Conditions
-              **Permission**: Administrator
-      memberships:
-        allOf:
-          - $ref: './link.yml'
-          - description: |-
-              Link to collection of all the group's memberships. The list will only include the memberships in projects
-              in which the requesting user has the necessary permissions.
-
-              **Resource**: MemberCollection
-
-              # Conditions
-              **Permission**: `view members` or `manage members` in any project
-      members:
-        type: array
-        items:
-          allOf:
-            - $ref: './link.yml'
-            - description: |-
-                One of the members of the group.
-
-                **Resource**: User
-
-                # Conditions
-                **Permission**: `manage members` in any project to read & admin to write
-
-example:
-  _type: Group
-  id: 9
-  name: Stormtroopers
-  createdAt: '2022-09-23T11:06:36.024Z'
-  updatedAt: '2022-09-23T11:06:36.024Z'
-  _links:
-    self:
-      href: '/api/v3/groups/9'
-      title: Stormtroopers
-    delete:
-      href: '/api/v3/group/9'
-      method: delete
-    memberships:
-      href: '/api/v3/memberships?filters=[{"principal":{"operator":"=","values":["9"]}}]'
-      title: Memberships
-    updateImmediately:
-      href: '/api/v3/group/9'
-      method: patch
-    members:
-      - href: '/api/v3/users/363'
-        title: ST-097E
-      - href: '/api/v3/users/60'
-        title: ST-C-334
+      _type:
+        type: string
+        enum:
+          - Group
+      _embedded:
+        type: object
+        properties:
+          members:
+            type: array
+            description: Embedded list of members.
+            items:
+              - $ref: './user_model.yml'
+      _links:
+        type: object
+        properties:
+          members:
+            type: array
+            items:
+              allOf:
+                - $ref: './link.yml'
+                - description: |-
+                    A member of the group
+
+                    # Conditions:
+
+                    - user has permission `manage_members` in any project
+
+                    **Resource**: User
+          delete:
+            allOf:
+              - $ref: './link.yml'
+              - description: |-
+                  An href to delete the group.
+
+                  # Conditions:
+
+                  - `admin`
+          updateImmediately:
+            allOf:
+              - $ref: './link.yml'
+              - description: |-
+                  An href to update the group.
+
+                  # Conditions:
+
+                  - `admin`
+
+                  **Resource**: Group

docs/api/apiv3/components/schemas/placeholder_user_collection_model.yml

@@ -0,0 +1,46 @@
+# Schema: PlaceholderUserCollectionModel
+---
+allOf:
+  - $ref: './collection_model.yml'
+  - type: object
+    required:
+      - _links
+      - _embedded
+    properties:
+      _links:
+        type: object
+        required:
+          - self
+        properties:
+          self:
+            allOf:
+              - $ref: "./link.yml"
+              - description: |-
+                  This placeholder user collection
+
+                  **Resource**: Collection
+      _embedded:
+        type: object
+        required:
+          - elements
+        properties:
+          elements:
+            type: array
+            items:
+              $ref: './placeholder_user_model.yml'
+
+example:
+  _type: Collection
+  total: 2
+  count: 2
+  _links:
+    self:
+      href: '/api/v3/placeholder_users'
+  _embedded:
+    elements:
+      - _hint: PlaceholderUser resource shortened for brevity
+        _type: PlaceholderUser
+        id: 1337
+      - _hint: PlaceholderUser resource shortened for brevity
+        _type: PlaceholderUser
+        id: 1338

docs/api/apiv3/components/schemas/placeholder_user_create_model.yml

@@ -0,0 +1,7 @@
+# Schema: PlaceholderUserCreateModel
+---
+type: object
+properties:
+  name:
+    type: string
+    description: The new name of the placeholder user to be created.

docs/api/apiv3/components/schemas/placeholder_user_model.yml

@@ -0,0 +1,50 @@
+# Schema: PlaceholderUserModel
+---
+allOf:
+  - $ref: './principal_model.yml'
+  - type: object
+    required:
+      - _type
+    properties:
+      _type:
+        type: string
+        enum:
+          - PlaceholderUser
+      status:
+        type: string
+        description: |-
+          The current activation status of the placeholder user.
+
+          # Conditions
+
+          - User has `manage_placeholder_user` permission globally
+      _links:
+        type: object
+        required:
+          - showUser
+        properties:
+          showUser:
+            allOf:
+              - $ref: './link.yml'
+              - description: |-
+                  A relative path to show the placeholder user in the web application.
+          delete:
+            allOf:
+              - $ref: './link.yml'
+              - description: |-
+                  An href to delete the placeholder user.
+
+                  # Conditions:
+
+                  - `manage_placeholder_user`
+          updateImmediately:
+            allOf:
+              - $ref: './link.yml'
+              - description: |-
+                  An href to update the placeholder user.
+
+                  # Conditions:
+
+                  - `manage_placeholder_user`
+
+                  **Resource**: PlaceholderUser