Changeset 14058

Timestamp:

10/24/2024 06:29:17 PM (8 months ago)

Author:

imath

Message:

Document the Messages component v2 REST API routes

Props espellcaste

See #9145
Closes ​https://github.com/buddypress/buddypress/pull/388

Location:

trunk

Files:

• docs/developer/execution-contexts/rest-api/messages.md (added)
• docs/developer/execution-contexts/rest-api/reference.md (modified) (1 diff)
• docs/developer/manifest.json (modified) (1 diff)
• src/bp-messages/classes/class-bp-messages-rest-controller.php (modified) (8 diffs)

trunk/docs/developer/execution-contexts/rest-api/reference.md

@@ -29 +29 @@
 | Group Membership Requests | `/buddypress/v2/groups/<group_id>/membership-request` |
 | Group Invites | `/buddypress/v2/groups/<group_id>/invites` |
-| Private Messaging | `/buddypress/v2/messages` |
+| [Private Messaging](./messages.md) | `/buddypress/v2/messages` |
 | Screen Notifications | `/buddypress/v2/notifications` |
 | User Blogs | `/buddypress/v2/blogs` |

trunk/docs/developer/manifest.json

@@ -193 +193 @@
     },
     {
+        "title": "Private Messaging REST API routes",
+        "slug": "bp-rest-api-messages",
+        "markdown_source": "../developer/execution-contexts/rest-api/messages.md",
+        "parent": "bp-rest-api-reference"
+    },
+    {
         "title": "BuddyPress Functions",
         "slug": "bp-functions",

trunk/src/bp-messages/classes/class-bp-messages-rest-controller.php

@@ -63 +63 @@
             $thread_endpoint,
             array(
+                'args'        => array(
+                    'id' => array(
+                        'description' => __( 'A unique numeric ID for the Thread.', 'buddypress' ),
+                        'type'        => 'integer',
+                    ),
+                ),
                 array(
                     'methods'             => WP_REST_Server::READABLE,
@@ -1117 +1123 @@
     public function get_endpoint_args_for_item_schema( $method = WP_REST_Server::CREATABLE ) {
         $args                      = parent::get_endpoint_args_for_item_schema( $method );
-        $args['id']['description'] = __( 'ID of the Messages Thread.', 'buddypress' );
+        $args['id']['description'] = __( 'A unique numeric ID for the Thread.', 'buddypress' );
 
         if ( WP_REST_Server::CREATABLE === $method ) {
@@ -1123 +1129 @@
 
             // Edit the Thread ID description and default properties.
-            $args['id']['description'] = __( 'ID of the Messages Thread. Required when replying to an existing Thread.', 'buddypress' );
+            $args['id']['description'] = __( 'A unique numeric ID for the Thread. Required when replying to an existing Thread.', 'buddypress' );
             $args['id']['default']     = 0;
 
@@ -1156 +1162 @@
 
         } else {
+            unset( $args['sender_id'], $args['subject'], $args['message'], $args['recipients'] );
+
+            $args['user_id'] = array(
+                'description'       => __( 'The user ID to get the thread for.', 'buddypress' ),
+                'required'          => false,
+                'type'              => 'integer',
+                'sanitize_callback' => 'absint',
+                'validate_callback' => 'rest_validate_request_arg',
+            );
+
             if ( WP_REST_Server::EDITABLE === $method ) {
+                unset( $args['message'], $args['recipients'], $args['subject'] );
                 $key = 'update_item';
 
@@ -1188 +1205 @@
             if ( WP_REST_Server::DELETABLE === $method ) {
                 $key = 'delete_item';
-
-                $args['user_id'] = array(
-                    'description'       => __( 'The user ID to remove from the thread', 'buddypress' ),
-                    'required'          => true,
-                    'type'              => 'integer',
-                    'sanitize_callback' => 'absint',
-                    'validate_callback' => 'rest_validate_request_arg',
-                    'default'           => bp_loggedin_user_id(),
-                );
-
-                unset( $args['sender_id'], $args['subject'], $args['message'], $args['recipients'] );
             }
 
             if ( WP_REST_Server::READABLE === $method ) {
-                unset( $args['sender_id'], $args['subject'], $args['message'], $args['recipients'] );
-
                 $key = 'get_item';
-
-                $args['user_id'] = array(
-                    'description'       => __( 'The user ID to get the thread for.', 'buddypress' ),
-                    'required'          => false,
-                    'type'              => 'integer',
-                    'sanitize_callback' => 'absint',
-                    'validate_callback' => 'rest_validate_request_arg',
-                );
 
                 $args['recipients_page'] = array(
@@ -1291 +1287 @@
                         'context'     => array( 'view', 'edit' ),
                         'description' => __( 'A unique numeric ID for the Thread.', 'buddypress' ),
+                        'readonly'    => true,
                         'type'        => 'integer',
                     ),
@@ -1376 +1373 @@
                     'date'                => array(
                         'context'     => array( 'view', 'edit' ),
-                        'description' => __( 'Dat of the latest message of the Thread, in the site\'s timezone.', 'buddypress' ),
+                        'description' => __( 'Date of the latest message of the Thread, in the site\'s timezone.', 'buddypress' ),
                         'readonly'    => true,
                         'type'        => array( 'string', 'null' ),
@@ -1405 +1402 @@
                     'recipients'          => array(
                         'context'     => array( 'view', 'edit' ),
-                        'description' => __( 'The list of recipient User Objects involved into the Thread.', 'buddypress' ),
+                        'description' => __( 'The list of Avatar URLs for the recipient involved into the Thread.', 'buddypress' ),
                         'type'        => 'array',
                         'items'       => array(