@mytechtoday/augment-extensions 0.5.0 → 1.2.0

package/augment-extensions/domain-rules/wordpress-plugin/rules/rest-api.md

@@ -1,818 +1,818 @@
-# REST API Development
-
-## Overview
-
-This guide covers WordPress REST API development for plugins including custom endpoints, authentication, permissions, validation, and modifying existing endpoints.
-
----
-
-## Register Custom Endpoints
-
-### Basic GET Endpoint
-
-```php
-<?php
-/**
- * Register custom REST API endpoint
- */
-function my_plugin_register_api_routes() {
-    register_rest_route( 'my-plugin/v1', '/items', array(
-        'methods'             => 'GET',
-        'callback'            => 'my_plugin_get_items',
-        'permission_callback' => '__return_true', // Public endpoint
-    ) );
-}
-add_action( 'rest_api_init', 'my_plugin_register_api_routes' );
-
-/**
- * Callback function for GET endpoint
- */
-function my_plugin_get_items( $request ) {
-    $items = array(
-        array(
-            'id'          => 1,
-            'title'       => 'Item 1',
-            'description' => 'First item',
-        ),
-        array(
-            'id'          => 2,
-            'title'       => 'Item 2',
-            'description' => 'Second item',
-        ),
-    );
-    
-    return new WP_REST_Response( $items, 200 );
-}
-```
-
-**Access endpoint:**
-```
-GET https://example.com/wp-json/my-plugin/v1/items
-```
-
-### Complete CRUD Endpoints
-
-```php
-<?php
-/**
- * Register CRUD endpoints
- */
-function my_plugin_register_crud_routes() {
-    $namespace = 'my-plugin/v1';
-    $base = 'items';
-    
-    // GET - List items
-    register_rest_route( $namespace, '/' . $base, array(
-        'methods'             => 'GET',
-        'callback'            => 'my_plugin_get_items',
-        'permission_callback' => '__return_true',
-        'args'                => my_plugin_get_collection_params(),
-    ) );
-    
-    // POST - Create item
-    register_rest_route( $namespace, '/' . $base, array(
-        'methods'             => 'POST',
-        'callback'            => 'my_plugin_create_item',
-        'permission_callback' => 'my_plugin_create_item_permissions_check',
-        'args'                => my_plugin_get_item_schema(),
-    ) );
-    
-    // GET - Retrieve single item
-    register_rest_route( $namespace, '/' . $base . '/(?P<id>\d+)', array(
-        'methods'             => 'GET',
-        'callback'            => 'my_plugin_get_item',
-        'permission_callback' => '__return_true',
-        'args'                => array(
-            'id' => array(
-                'validate_callback' => function( $param ) {
-                    return is_numeric( $param );
-                },
-            ),
-        ),
-    ) );
-    
-    // PUT/PATCH - Update item
-    register_rest_route( $namespace, '/' . $base . '/(?P<id>\d+)', array(
-        'methods'             => array( 'PUT', 'PATCH' ),
-        'callback'            => 'my_plugin_update_item',
-        'permission_callback' => 'my_plugin_update_item_permissions_check',
-        'args'                => my_plugin_get_item_schema(),
-    ) );
-    
-    // DELETE - Delete item
-    register_rest_route( $namespace, '/' . $base . '/(?P<id>\d+)', array(
-        'methods'             => 'DELETE',
-        'callback'            => 'my_plugin_delete_item',
-        'permission_callback' => 'my_plugin_delete_item_permissions_check',
-    ) );
-}
-add_action( 'rest_api_init', 'my_plugin_register_crud_routes' );
-```
-
----
-
-## Callback Functions
-
-### GET Single Item
-
-```php
-<?php
-/**
- * Get single item
- */
-function my_plugin_get_item( $request ) {
-    $id = $request['id'];
-    
-    // Retrieve item from database
-    $item = get_post( $id );
-    
-    if ( ! $item || $item->post_type !== 'my_custom_post_type' ) {
-        return new WP_Error(
-            'not_found',
-            __( 'Item not found', 'my-plugin' ),
-            array( 'status' => 404 )
-        );
-    }
-    
-    $data = array(
-        'id'          => $item->ID,
-        'title'       => $item->post_title,
-        'content'     => $item->post_content,
-        'date'        => $item->post_date,
-        'modified'    => $item->post_modified,
-        'author'      => $item->post_author,
-    );
-    
-    return new WP_REST_Response( $data, 200 );
-}
-```
-
-### POST - Create Item
-
-```php
-<?php
-/**
- * Create item
- */
-function my_plugin_create_item( $request ) {
-    $title   = sanitize_text_field( $request['title'] );
-    $content = wp_kses_post( $request['content'] );
-    $status  = sanitize_text_field( $request['status'] );
-    
-    $post_id = wp_insert_post( array(
-        'post_title'   => $title,
-        'post_content' => $content,
-        'post_status'  => $status,
-        'post_type'    => 'my_custom_post_type',
-    ) );
-
-    if ( is_wp_error( $post_id ) ) {
-        return new WP_Error(
-            'create_failed',
-            __( 'Failed to create item', 'my-plugin' ),
-            array( 'status' => 500 )
-        );
-    }
-
-    $data = array(
-        'id'      => $post_id,
-        'title'   => $title,
-        'content' => $content,
-        'status'  => $status,
-    );
-
-    return new WP_REST_Response( $data, 201 );
-}
-```
-
-### PUT/PATCH - Update Item
-
-```php
-<?php
-/**
- * Update item
- */
-function my_plugin_update_item( $request ) {
-    $id = $request['id'];
-
-    // Check if item exists
-    $item = get_post( $id );
-    if ( ! $item || $item->post_type !== 'my_custom_post_type' ) {
-        return new WP_Error(
-            'not_found',
-            __( 'Item not found', 'my-plugin' ),
-            array( 'status' => 404 )
-        );
-    }
-
-    $update_data = array(
-        'ID' => $id,
-    );
-
-    if ( isset( $request['title'] ) ) {
-        $update_data['post_title'] = sanitize_text_field( $request['title'] );
-    }
-
-    if ( isset( $request['content'] ) ) {
-        $update_data['post_content'] = wp_kses_post( $request['content'] );
-    }
-
-    if ( isset( $request['status'] ) ) {
-        $update_data['post_status'] = sanitize_text_field( $request['status'] );
-    }
-
-    $result = wp_update_post( $update_data, true );
-
-    if ( is_wp_error( $result ) ) {
-        return new WP_Error(
-            'update_failed',
-            __( 'Failed to update item', 'my-plugin' ),
-            array( 'status' => 500 )
-        );
-    }
-
-    $updated_item = get_post( $id );
-    $data = array(
-        'id'      => $updated_item->ID,
-        'title'   => $updated_item->post_title,
-        'content' => $updated_item->post_content,
-        'status'  => $updated_item->post_status,
-    );
-
-    return new WP_REST_Response( $data, 200 );
-}
-```
-
-### DELETE - Delete Item
-
-```php
-<?php
-/**
- * Delete item
- */
-function my_plugin_delete_item( $request ) {
-    $id = $request['id'];
-
-    // Check if item exists
-    $item = get_post( $id );
-    if ( ! $item || $item->post_type !== 'my_custom_post_type' ) {
-        return new WP_Error(
-            'not_found',
-            __( 'Item not found', 'my-plugin' ),
-            array( 'status' => 404 )
-        );
-    }
-
-    // Delete permanently (true) or move to trash (false)
-    $result = wp_delete_post( $id, true );
-
-    if ( ! $result ) {
-        return new WP_Error(
-            'delete_failed',
-            __( 'Failed to delete item', 'my-plugin' ),
-            array( 'status' => 500 )
-        );
-    }
-
-    return new WP_REST_Response(
-        array(
-            'deleted' => true,
-            'id'      => $id,
-        ),
-        200
-    );
-}
-```
-
----
-
-## Permission Callbacks
-
-### Public Endpoint (No Authentication)
-
-```php
-<?php
-'permission_callback' => '__return_true',
-```
-
-### Require Authentication
-
-```php
-<?php
-function my_plugin_check_authentication() {
-    return is_user_logged_in();
-}
-
-'permission_callback' => 'my_plugin_check_authentication',
-```
-
-### Require Specific Capability
-
-```php
-<?php
-function my_plugin_create_item_permissions_check( $request ) {
-    return current_user_can( 'edit_posts' );
-}
-
-function my_plugin_delete_item_permissions_check( $request ) {
-    return current_user_can( 'delete_posts' );
-}
-
-'permission_callback' => 'my_plugin_create_item_permissions_check',
-```
-
-### Custom Permission Logic
-
-```php
-<?php
-function my_plugin_update_item_permissions_check( $request ) {
-    // Check if user is logged in
-    if ( ! is_user_logged_in() ) {
-        return new WP_Error(
-            'rest_forbidden',
-            __( 'You must be logged in to update items.', 'my-plugin' ),
-            array( 'status' => 401 )
-        );
-    }
-
-    // Check if user has capability
-    if ( ! current_user_can( 'edit_posts' ) ) {
-        return new WP_Error(
-            'rest_forbidden',
-            __( 'You do not have permission to edit items.', 'my-plugin' ),
-            array( 'status' => 403 )
-        );
-    }
-
-    // Check if user owns the resource
-    $id = $request['id'];
-    $post = get_post( $id );
-
-    if ( $post && $post->post_author != get_current_user_id() && ! current_user_can( 'edit_others_posts' ) ) {
-        return new WP_Error(
-            'rest_forbidden',
-            __( 'You can only edit your own items.', 'my-plugin' ),
-            array( 'status' => 403 )
-        );
-    }
-
-    return true;
-}
-
-'permission_callback' => 'my_plugin_update_item_permissions_check',
-```
-
----
-
-## Input Validation and Sanitization
-
-### Define Argument Schema
-
-```php
-<?php
-/**
- * Get item schema for validation
- */
-function my_plugin_get_item_schema() {
-    return array(
-        'title' => array(
-            'required'          => true,
-            'type'              => 'string',
-            'description'       => __( 'Item title', 'my-plugin' ),
-            'sanitize_callback' => 'sanitize_text_field',
-        ),
-        'content' => array(
-            'required'          => false,
-            'type'              => 'string',
-            'description'       => __( 'Item content', 'my-plugin' ),
-            'sanitize_callback' => 'wp_kses_post',
-        ),
-        'status' => array(
-            'required'          => false,
-            'type'              => 'string',
-            'description'       => __( 'Item status', 'my-plugin' ),
-            'enum'              => array( 'draft', 'publish', 'private' ),
-            'default'           => 'draft',
-            'sanitize_callback' => 'sanitize_text_field',
-        ),
-        'count' => array(
-            'required'          => false,
-            'type'              => 'integer',
-            'description'       => __( 'Item count', 'my-plugin' ),
-            'minimum'           => 0,
-            'maximum'           => 100,
-            'default'           => 0,
-        ),
-    );
-}
-```
-
-### Custom Validation
-
-```php
-<?php
-/**
- * Validate email
- */
-function my_plugin_validate_email( $param, $request, $key ) {
-    if ( ! is_email( $param ) ) {
-        return new WP_Error(
-            'invalid_email',
-            __( 'Invalid email address', 'my-plugin' )
-        );
-    }
-    return true;
-}
-
-/**
- * Validate URL
- */
-function my_plugin_validate_url( $param, $request, $key ) {
-    if ( ! filter_var( $param, FILTER_VALIDATE_URL ) ) {
-        return new WP_Error(
-            'invalid_url',
-            __( 'Invalid URL', 'my-plugin' )
-        );
-    }
-    return true;
-}
-
-// Use in args
-'args' => array(
-    'email' => array(
-        'required'          => true,
-        'validate_callback' => 'my_plugin_validate_email',
-        'sanitize_callback' => 'sanitize_email',
-    ),
-    'website' => array(
-        'required'          => false,
-        'validate_callback' => 'my_plugin_validate_url',
-        'sanitize_callback' => 'esc_url_raw',
-    ),
-),
-
----
-
-## Query Parameters
-
-### Accept Query Parameters
-
-```php
-<?php
-/**
- * Get collection parameters
- */
-function my_plugin_get_collection_params() {
-    return array(
-        'per_page' => array(
-            'description'       => __( 'Items per page', 'my-plugin' ),
-            'type'              => 'integer',
-            'default'           => 10,
-            'minimum'           => 1,
-            'maximum'           => 100,
-            'sanitize_callback' => 'absint',
-        ),
-        'page' => array(
-            'description'       => __( 'Page number', 'my-plugin' ),
-            'type'              => 'integer',
-            'default'           => 1,
-            'minimum'           => 1,
-            'sanitize_callback' => 'absint',
-        ),
-        'search' => array(
-            'description'       => __( 'Search term', 'my-plugin' ),
-            'type'              => 'string',
-            'sanitize_callback' => 'sanitize_text_field',
-        ),
-        'orderby' => array(
-            'description'       => __( 'Order by field', 'my-plugin' ),
-            'type'              => 'string',
-            'default'           => 'date',
-            'enum'              => array( 'date', 'title', 'modified' ),
-            'sanitize_callback' => 'sanitize_text_field',
-        ),
-        'order' => array(
-            'description'       => __( 'Order direction', 'my-plugin' ),
-            'type'              => 'string',
-            'default'           => 'DESC',
-            'enum'              => array( 'ASC', 'DESC' ),
-            'sanitize_callback' => 'sanitize_text_field',
-        ),
-    );
-}
-
-/**
- * Get items with query parameters
- */
-function my_plugin_get_items( $request ) {
-    $per_page = $request->get_param( 'per_page' );
-    $page     = $request->get_param( 'page' );
-    $search   = $request->get_param( 'search' );
-    $orderby  = $request->get_param( 'orderby' );
-    $order    = $request->get_param( 'order' );
-
-    $args = array(
-        'post_type'      => 'my_custom_post_type',
-        'posts_per_page' => $per_page,
-        'paged'          => $page,
-        'orderby'        => $orderby,
-        'order'          => $order,
-    );
-
-    if ( ! empty( $search ) ) {
-        $args['s'] = $search;
-    }
-
-    $query = new WP_Query( $args );
-
-    $items = array();
-    foreach ( $query->posts as $post ) {
-        $items[] = array(
-            'id'      => $post->ID,
-            'title'   => $post->post_title,
-            'content' => $post->post_content,
-            'date'    => $post->post_date,
-        );
-    }
-
-    $response = new WP_REST_Response( $items, 200 );
-
-    // Add pagination headers
-    $response->header( 'X-WP-Total', $query->found_posts );
-    $response->header( 'X-WP-TotalPages', $query->max_num_pages );
-
-    return $response;
-}
-```
-
-**Usage:**
-```
-GET /wp-json/my-plugin/v1/items?per_page=20&page=2&orderby=title&order=ASC&search=keyword
-```
-
----
-
-## Authentication
-
-### Application Passwords (WordPress 5.6+)
-
-WordPress natively supports Application Passwords for REST API authentication.
-
-**No additional code needed** - Users create application passwords in their profile.
-
-**Usage:**
-```bash
-curl -X GET https://example.com/wp-json/my-plugin/v1/items \
-  --user "username:application-password"
-```
-
-### Custom API Key Authentication
-
-```php
-<?php
-/**
- * Validate API key
- */
-function my_plugin_validate_api_key( $request ) {
-    $api_key = $request->get_header( 'X-API-Key' );
-
-    if ( empty( $api_key ) ) {
-        return new WP_Error(
-            'rest_forbidden',
-            __( 'API key is required', 'my-plugin' ),
-            array( 'status' => 401 )
-        );
-    }
-
-    // Validate API key against stored keys
-    $valid_keys = get_option( 'my_plugin_api_keys', array() );
-
-    if ( ! in_array( $api_key, $valid_keys, true ) ) {
-        return new WP_Error(
-            'rest_forbidden',
-            __( 'Invalid API key', 'my-plugin' ),
-            array( 'status' => 401 )
-        );
-    }
-
-    return true;
-}
-
-// Use in endpoint
-register_rest_route( 'my-plugin/v1', '/secure-data', array(
-    'methods'             => 'GET',
-    'callback'            => 'my_plugin_get_secure_data',
-    'permission_callback' => 'my_plugin_validate_api_key',
-) );
-```
-
-**Usage:**
-```bash
-curl -X GET https://example.com/wp-json/my-plugin/v1/secure-data \
-  -H "X-API-Key: your-api-key-here"
-```
-
----
-
-## Modify Existing Endpoints
-
-### Add Custom Fields to Posts
-
-```php
-<?php
-/**
- * Add custom field to post response
- */
-function my_plugin_add_custom_field_to_post() {
-    register_rest_field( 'post', 'custom_field', array(
-        'get_callback'    => 'my_plugin_get_custom_field',
-        'update_callback' => 'my_plugin_update_custom_field',
-        'schema'          => array(
-            'description' => __( 'Custom field', 'my-plugin' ),
-            'type'        => 'string',
-        ),
-    ) );
-}
-add_action( 'rest_api_init', 'my_plugin_add_custom_field_to_post' );
-
-/**
- * Get custom field value
- */
-function my_plugin_get_custom_field( $post ) {
-    return get_post_meta( $post['id'], '_custom_field', true );
-}
-
-/**
- * Update custom field value
- */
-function my_plugin_update_custom_field( $value, $post ) {
-    return update_post_meta( $post->ID, '_custom_field', sanitize_text_field( $value ) );
-}
-```
-
-### Add Multiple Custom Fields
-
-```php
-<?php
-/**
- * Add multiple custom fields
- */
-function my_plugin_add_multiple_fields() {
-    register_rest_field( 'post', 'view_count', array(
-        'get_callback' => function( $post ) {
-            return (int) get_post_meta( $post['id'], 'views', true );
-        },
-        'schema'       => array(
-            'description' => __( 'Number of views', 'my-plugin' ),
-            'type'        => 'integer',
-        ),
-    ) );
-
-    register_rest_field( 'post', 'reading_time', array(
-        'get_callback' => function( $post ) {
-            $content = get_post_field( 'post_content', $post['id'] );
-            $word_count = str_word_count( strip_tags( $content ) );
-            return ceil( $word_count / 200 ); // Assume 200 words per minute
-        },
-        'schema'       => array(
-            'description' => __( 'Estimated reading time in minutes', 'my-plugin' ),
-            'type'        => 'integer',
-        ),
-    ) );
-}
-add_action( 'rest_api_init', 'my_plugin_add_multiple_fields' );
-```
-
-### Modify Response Data
-
-```php
-<?php
-/**
- * Modify post response
- */
-function my_plugin_modify_post_response( $response, $post, $request ) {
-    $data = $response->get_data();
-
-    // Add custom data
-    $data['custom_data'] = array(
-        'views'        => get_post_meta( $post->ID, 'views', true ),
-        'likes'        => get_post_meta( $post->ID, 'likes', true ),
-        'is_featured'  => (bool) get_post_meta( $post->ID, 'featured', true ),
-    );
-
-    // Remove sensitive data
-    unset( $data['author'] );
-
-    $response->set_data( $data );
-
-    return $response;
-}
-add_filter( 'rest_prepare_post', 'my_plugin_modify_post_response', 10, 3 );
-```
-
----
-
-## Best Practices
-
-### Endpoint Design
-
-1. **Use versioning**: Include version in namespace (`my-plugin/v1`)
-2. **Use nouns for resources**: `/items`, `/users`, not `/get-items`
-3. **Use HTTP methods correctly**: GET (read), POST (create), PUT/PATCH (update), DELETE (delete)
-4. **Use proper status codes**: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 500 (Server Error)
-5. **Return consistent responses**: Use `WP_REST_Response` or `WP_Error`
-
-### Security
-
-1. **Always validate permissions**: Never use `__return_true` for write operations
-2. **Sanitize input**: Use appropriate sanitization callbacks
-3. **Validate input**: Use validation callbacks and schema
-4. **Escape output**: Use `esc_html()`, `esc_url()`, etc.
-5. **Use nonces for admin**: For admin-ajax.php endpoints (not REST API)
-6. **Rate limiting**: Consider implementing rate limiting for public endpoints
-
-### Performance
-
-1. **Limit query results**: Set maximum `per_page` value
-2. **Use pagination**: Always paginate large result sets
-3. **Cache responses**: Use transients for expensive queries
-4. **Optimize queries**: Use `WP_Query` efficiently
-5. **Lazy load data**: Don't include unnecessary data in responses
-
-### Documentation
-
-1. **Document endpoints**: Provide clear descriptions
-2. **Document parameters**: Describe all parameters and their types
-3. **Provide examples**: Include example requests and responses
-4. **Use schema**: Define proper schema for validation and documentation
-
----
-
-## Common Pitfalls
-
-### ❌ DON'T
-
-```php
-// Don't use __return_true for write operations
-register_rest_route( 'my-plugin/v1', '/items', array(
-    'methods'             => 'POST',
-    'callback'            => 'create_item',
-    'permission_callback' => '__return_true', // BAD!
-) );
-
-// Don't forget to sanitize input
-function create_item( $request ) {
-    $title = $request['title']; // BAD! Not sanitized
-    wp_insert_post( array( 'post_title' => $title ) );
-}
-
-// Don't return raw data
-function get_item( $request ) {
-    return get_post( $request['id'] ); // BAD! Returns WP_Post object
-}
-
-// Don't forget error handling
-function get_item( $request ) {
-    $item = get_post( $request['id'] );
-    return new WP_REST_Response( $item, 200 ); // BAD! No error check
-}
-```
-
-### ✅ DO
-
-```php
-// Use proper permission checks
-register_rest_route( 'my-plugin/v1', '/items', array(
-    'methods'             => 'POST',
-    'callback'            => 'create_item',
-    'permission_callback' => 'check_create_permission', // GOOD!
-) );
-
-// Always sanitize input
-function create_item( $request ) {
-    $title = sanitize_text_field( $request['title'] ); // GOOD!
-    wp_insert_post( array( 'post_title' => $title ) );
-}
-
-// Return formatted data
-function get_item( $request ) {
-    $post = get_post( $request['id'] );
-    $data = array(
-        'id'    => $post->ID,
-        'title' => $post->post_title,
-    );
-    return new WP_REST_Response( $data, 200 ); // GOOD!
-}
-
-// Always handle errors
-function get_item( $request ) {
-    $item = get_post( $request['id'] );
-
-    if ( ! $item ) {
-        return new WP_Error( 'not_found', 'Item not found', array( 'status' => 404 ) );
-    }
-
-    return new WP_REST_Response( $item, 200 ); // GOOD!
-}
-```
-
+# REST API Development
+
+## Overview
+
+This guide covers WordPress REST API development for plugins including custom endpoints, authentication, permissions, validation, and modifying existing endpoints.
+
+---
+
+## Register Custom Endpoints
+
+### Basic GET Endpoint
+
+```php
+<?php
+/**
+ * Register custom REST API endpoint
+ */
+function my_plugin_register_api_routes() {
+    register_rest_route( 'my-plugin/v1', '/items', array(
+        'methods'             => 'GET',
+        'callback'            => 'my_plugin_get_items',
+        'permission_callback' => '__return_true', // Public endpoint
+    ) );
+}
+add_action( 'rest_api_init', 'my_plugin_register_api_routes' );
+
+/**
+ * Callback function for GET endpoint
+ */
+function my_plugin_get_items( $request ) {
+    $items = array(
+        array(
+            'id'          => 1,
+            'title'       => 'Item 1',
+            'description' => 'First item',
+        ),
+        array(
+            'id'          => 2,
+            'title'       => 'Item 2',
+            'description' => 'Second item',
+        ),
+    );
+    
+    return new WP_REST_Response( $items, 200 );
+}
+```
+
+**Access endpoint:**
+```
+GET https://example.com/wp-json/my-plugin/v1/items
+```
+
+### Complete CRUD Endpoints
+
+```php
+<?php
+/**
+ * Register CRUD endpoints
+ */
+function my_plugin_register_crud_routes() {
+    $namespace = 'my-plugin/v1';
+    $base = 'items';
+    
+    // GET - List items
+    register_rest_route( $namespace, '/' . $base, array(
+        'methods'             => 'GET',
+        'callback'            => 'my_plugin_get_items',
+        'permission_callback' => '__return_true',
+        'args'                => my_plugin_get_collection_params(),
+    ) );
+    
+    // POST - Create item
+    register_rest_route( $namespace, '/' . $base, array(
+        'methods'             => 'POST',
+        'callback'            => 'my_plugin_create_item',
+        'permission_callback' => 'my_plugin_create_item_permissions_check',
+        'args'                => my_plugin_get_item_schema(),
+    ) );
+    
+    // GET - Retrieve single item
+    register_rest_route( $namespace, '/' . $base . '/(?P<id>\d+)', array(
+        'methods'             => 'GET',
+        'callback'            => 'my_plugin_get_item',
+        'permission_callback' => '__return_true',
+        'args'                => array(
+            'id' => array(
+                'validate_callback' => function( $param ) {
+                    return is_numeric( $param );
+                },
+            ),
+        ),
+    ) );
+    
+    // PUT/PATCH - Update item
+    register_rest_route( $namespace, '/' . $base . '/(?P<id>\d+)', array(
+        'methods'             => array( 'PUT', 'PATCH' ),
+        'callback'            => 'my_plugin_update_item',
+        'permission_callback' => 'my_plugin_update_item_permissions_check',
+        'args'                => my_plugin_get_item_schema(),
+    ) );
+    
+    // DELETE - Delete item
+    register_rest_route( $namespace, '/' . $base . '/(?P<id>\d+)', array(
+        'methods'             => 'DELETE',
+        'callback'            => 'my_plugin_delete_item',
+        'permission_callback' => 'my_plugin_delete_item_permissions_check',
+    ) );
+}
+add_action( 'rest_api_init', 'my_plugin_register_crud_routes' );
+```
+
+---
+
+## Callback Functions
+
+### GET Single Item
+
+```php
+<?php
+/**
+ * Get single item
+ */
+function my_plugin_get_item( $request ) {
+    $id = $request['id'];
+    
+    // Retrieve item from database
+    $item = get_post( $id );
+    
+    if ( ! $item || $item->post_type !== 'my_custom_post_type' ) {
+        return new WP_Error(
+            'not_found',
+            __( 'Item not found', 'my-plugin' ),
+            array( 'status' => 404 )
+        );
+    }
+    
+    $data = array(
+        'id'          => $item->ID,
+        'title'       => $item->post_title,
+        'content'     => $item->post_content,
+        'date'        => $item->post_date,
+        'modified'    => $item->post_modified,
+        'author'      => $item->post_author,
+    );
+    
+    return new WP_REST_Response( $data, 200 );
+}
+```
+
+### POST - Create Item
+
+```php
+<?php
+/**
+ * Create item
+ */
+function my_plugin_create_item( $request ) {
+    $title   = sanitize_text_field( $request['title'] );
+    $content = wp_kses_post( $request['content'] );
+    $status  = sanitize_text_field( $request['status'] );
+    
+    $post_id = wp_insert_post( array(
+        'post_title'   => $title,
+        'post_content' => $content,
+        'post_status'  => $status,
+        'post_type'    => 'my_custom_post_type',
+    ) );
+
+    if ( is_wp_error( $post_id ) ) {
+        return new WP_Error(
+            'create_failed',
+            __( 'Failed to create item', 'my-plugin' ),
+            array( 'status' => 500 )
+        );
+    }
+
+    $data = array(
+        'id'      => $post_id,
+        'title'   => $title,
+        'content' => $content,
+        'status'  => $status,
+    );
+
+    return new WP_REST_Response( $data, 201 );
+}
+```
+
+### PUT/PATCH - Update Item
+
+```php
+<?php
+/**
+ * Update item
+ */
+function my_plugin_update_item( $request ) {
+    $id = $request['id'];
+
+    // Check if item exists
+    $item = get_post( $id );
+    if ( ! $item || $item->post_type !== 'my_custom_post_type' ) {
+        return new WP_Error(
+            'not_found',
+            __( 'Item not found', 'my-plugin' ),
+            array( 'status' => 404 )
+        );
+    }
+
+    $update_data = array(
+        'ID' => $id,
+    );
+
+    if ( isset( $request['title'] ) ) {
+        $update_data['post_title'] = sanitize_text_field( $request['title'] );
+    }
+
+    if ( isset( $request['content'] ) ) {
+        $update_data['post_content'] = wp_kses_post( $request['content'] );
+    }
+
+    if ( isset( $request['status'] ) ) {
+        $update_data['post_status'] = sanitize_text_field( $request['status'] );
+    }
+
+    $result = wp_update_post( $update_data, true );
+
+    if ( is_wp_error( $result ) ) {
+        return new WP_Error(
+            'update_failed',
+            __( 'Failed to update item', 'my-plugin' ),
+            array( 'status' => 500 )
+        );
+    }
+
+    $updated_item = get_post( $id );
+    $data = array(
+        'id'      => $updated_item->ID,
+        'title'   => $updated_item->post_title,
+        'content' => $updated_item->post_content,
+        'status'  => $updated_item->post_status,
+    );
+
+    return new WP_REST_Response( $data, 200 );
+}
+```
+
+### DELETE - Delete Item
+
+```php
+<?php
+/**
+ * Delete item
+ */
+function my_plugin_delete_item( $request ) {
+    $id = $request['id'];
+
+    // Check if item exists
+    $item = get_post( $id );
+    if ( ! $item || $item->post_type !== 'my_custom_post_type' ) {
+        return new WP_Error(
+            'not_found',
+            __( 'Item not found', 'my-plugin' ),
+            array( 'status' => 404 )
+        );
+    }
+
+    // Delete permanently (true) or move to trash (false)
+    $result = wp_delete_post( $id, true );
+
+    if ( ! $result ) {
+        return new WP_Error(
+            'delete_failed',
+            __( 'Failed to delete item', 'my-plugin' ),
+            array( 'status' => 500 )
+        );
+    }
+
+    return new WP_REST_Response(
+        array(
+            'deleted' => true,
+            'id'      => $id,
+        ),
+        200
+    );
+}
+```
+
+---
+
+## Permission Callbacks
+
+### Public Endpoint (No Authentication)
+
+```php
+<?php
+'permission_callback' => '__return_true',
+```
+
+### Require Authentication
+
+```php
+<?php
+function my_plugin_check_authentication() {
+    return is_user_logged_in();
+}
+
+'permission_callback' => 'my_plugin_check_authentication',
+```
+
+### Require Specific Capability
+
+```php
+<?php
+function my_plugin_create_item_permissions_check( $request ) {
+    return current_user_can( 'edit_posts' );
+}
+
+function my_plugin_delete_item_permissions_check( $request ) {
+    return current_user_can( 'delete_posts' );
+}
+
+'permission_callback' => 'my_plugin_create_item_permissions_check',
+```
+
+### Custom Permission Logic
+
+```php
+<?php
+function my_plugin_update_item_permissions_check( $request ) {
+    // Check if user is logged in
+    if ( ! is_user_logged_in() ) {
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'You must be logged in to update items.', 'my-plugin' ),
+            array( 'status' => 401 )
+        );
+    }
+
+    // Check if user has capability
+    if ( ! current_user_can( 'edit_posts' ) ) {
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'You do not have permission to edit items.', 'my-plugin' ),
+            array( 'status' => 403 )
+        );
+    }
+
+    // Check if user owns the resource
+    $id = $request['id'];
+    $post = get_post( $id );
+
+    if ( $post && $post->post_author != get_current_user_id() && ! current_user_can( 'edit_others_posts' ) ) {
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'You can only edit your own items.', 'my-plugin' ),
+            array( 'status' => 403 )
+        );
+    }
+
+    return true;
+}
+
+'permission_callback' => 'my_plugin_update_item_permissions_check',
+```
+
+---
+
+## Input Validation and Sanitization
+
+### Define Argument Schema
+
+```php
+<?php
+/**
+ * Get item schema for validation
+ */
+function my_plugin_get_item_schema() {
+    return array(
+        'title' => array(
+            'required'          => true,
+            'type'              => 'string',
+            'description'       => __( 'Item title', 'my-plugin' ),
+            'sanitize_callback' => 'sanitize_text_field',
+        ),
+        'content' => array(
+            'required'          => false,
+            'type'              => 'string',
+            'description'       => __( 'Item content', 'my-plugin' ),
+            'sanitize_callback' => 'wp_kses_post',
+        ),
+        'status' => array(
+            'required'          => false,
+            'type'              => 'string',
+            'description'       => __( 'Item status', 'my-plugin' ),
+            'enum'              => array( 'draft', 'publish', 'private' ),
+            'default'           => 'draft',
+            'sanitize_callback' => 'sanitize_text_field',
+        ),
+        'count' => array(
+            'required'          => false,
+            'type'              => 'integer',
+            'description'       => __( 'Item count', 'my-plugin' ),
+            'minimum'           => 0,
+            'maximum'           => 100,
+            'default'           => 0,
+        ),
+    );
+}
+```
+
+### Custom Validation
+
+```php
+<?php
+/**
+ * Validate email
+ */
+function my_plugin_validate_email( $param, $request, $key ) {
+    if ( ! is_email( $param ) ) {
+        return new WP_Error(
+            'invalid_email',
+            __( 'Invalid email address', 'my-plugin' )
+        );
+    }
+    return true;
+}
+
+/**
+ * Validate URL
+ */
+function my_plugin_validate_url( $param, $request, $key ) {
+    if ( ! filter_var( $param, FILTER_VALIDATE_URL ) ) {
+        return new WP_Error(
+            'invalid_url',
+            __( 'Invalid URL', 'my-plugin' )
+        );
+    }
+    return true;
+}
+
+// Use in args
+'args' => array(
+    'email' => array(
+        'required'          => true,
+        'validate_callback' => 'my_plugin_validate_email',
+        'sanitize_callback' => 'sanitize_email',
+    ),
+    'website' => array(
+        'required'          => false,
+        'validate_callback' => 'my_plugin_validate_url',
+        'sanitize_callback' => 'esc_url_raw',
+    ),
+),
+
+---
+
+## Query Parameters
+
+### Accept Query Parameters
+
+```php
+<?php
+/**
+ * Get collection parameters
+ */
+function my_plugin_get_collection_params() {
+    return array(
+        'per_page' => array(
+            'description'       => __( 'Items per page', 'my-plugin' ),
+            'type'              => 'integer',
+            'default'           => 10,
+            'minimum'           => 1,
+            'maximum'           => 100,
+            'sanitize_callback' => 'absint',
+        ),
+        'page' => array(
+            'description'       => __( 'Page number', 'my-plugin' ),
+            'type'              => 'integer',
+            'default'           => 1,
+            'minimum'           => 1,
+            'sanitize_callback' => 'absint',
+        ),
+        'search' => array(
+            'description'       => __( 'Search term', 'my-plugin' ),
+            'type'              => 'string',
+            'sanitize_callback' => 'sanitize_text_field',
+        ),
+        'orderby' => array(
+            'description'       => __( 'Order by field', 'my-plugin' ),
+            'type'              => 'string',
+            'default'           => 'date',
+            'enum'              => array( 'date', 'title', 'modified' ),
+            'sanitize_callback' => 'sanitize_text_field',
+        ),
+        'order' => array(
+            'description'       => __( 'Order direction', 'my-plugin' ),
+            'type'              => 'string',
+            'default'           => 'DESC',
+            'enum'              => array( 'ASC', 'DESC' ),
+            'sanitize_callback' => 'sanitize_text_field',
+        ),
+    );
+}
+
+/**
+ * Get items with query parameters
+ */
+function my_plugin_get_items( $request ) {
+    $per_page = $request->get_param( 'per_page' );
+    $page     = $request->get_param( 'page' );
+    $search   = $request->get_param( 'search' );
+    $orderby  = $request->get_param( 'orderby' );
+    $order    = $request->get_param( 'order' );
+
+    $args = array(
+        'post_type'      => 'my_custom_post_type',
+        'posts_per_page' => $per_page,
+        'paged'          => $page,
+        'orderby'        => $orderby,
+        'order'          => $order,
+    );
+
+    if ( ! empty( $search ) ) {
+        $args['s'] = $search;
+    }
+
+    $query = new WP_Query( $args );
+
+    $items = array();
+    foreach ( $query->posts as $post ) {
+        $items[] = array(
+            'id'      => $post->ID,
+            'title'   => $post->post_title,
+            'content' => $post->post_content,
+            'date'    => $post->post_date,
+        );
+    }
+
+    $response = new WP_REST_Response( $items, 200 );
+
+    // Add pagination headers
+    $response->header( 'X-WP-Total', $query->found_posts );
+    $response->header( 'X-WP-TotalPages', $query->max_num_pages );
+
+    return $response;
+}
+```
+
+**Usage:**
+```
+GET /wp-json/my-plugin/v1/items?per_page=20&page=2&orderby=title&order=ASC&search=keyword
+```
+
+---
+
+## Authentication
+
+### Application Passwords (WordPress 5.6+)
+
+WordPress natively supports Application Passwords for REST API authentication.
+
+**No additional code needed** - Users create application passwords in their profile.
+
+**Usage:**
+```bash
+curl -X GET https://example.com/wp-json/my-plugin/v1/items \
+  --user "username:application-password"
+```
+
+### Custom API Key Authentication
+
+```php
+<?php
+/**
+ * Validate API key
+ */
+function my_plugin_validate_api_key( $request ) {
+    $api_key = $request->get_header( 'X-API-Key' );
+
+    if ( empty( $api_key ) ) {
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'API key is required', 'my-plugin' ),
+            array( 'status' => 401 )
+        );
+    }
+
+    // Validate API key against stored keys
+    $valid_keys = get_option( 'my_plugin_api_keys', array() );
+
+    if ( ! in_array( $api_key, $valid_keys, true ) ) {
+        return new WP_Error(
+            'rest_forbidden',
+            __( 'Invalid API key', 'my-plugin' ),
+            array( 'status' => 401 )
+        );
+    }
+
+    return true;
+}
+
+// Use in endpoint
+register_rest_route( 'my-plugin/v1', '/secure-data', array(
+    'methods'             => 'GET',
+    'callback'            => 'my_plugin_get_secure_data',
+    'permission_callback' => 'my_plugin_validate_api_key',
+) );
+```
+
+**Usage:**
+```bash
+curl -X GET https://example.com/wp-json/my-plugin/v1/secure-data \
+  -H "X-API-Key: your-api-key-here"
+```
+
+---
+
+## Modify Existing Endpoints
+
+### Add Custom Fields to Posts
+
+```php
+<?php
+/**
+ * Add custom field to post response
+ */
+function my_plugin_add_custom_field_to_post() {
+    register_rest_field( 'post', 'custom_field', array(
+        'get_callback'    => 'my_plugin_get_custom_field',
+        'update_callback' => 'my_plugin_update_custom_field',
+        'schema'          => array(
+            'description' => __( 'Custom field', 'my-plugin' ),
+            'type'        => 'string',
+        ),
+    ) );
+}
+add_action( 'rest_api_init', 'my_plugin_add_custom_field_to_post' );
+
+/**
+ * Get custom field value
+ */
+function my_plugin_get_custom_field( $post ) {
+    return get_post_meta( $post['id'], '_custom_field', true );
+}
+
+/**
+ * Update custom field value
+ */
+function my_plugin_update_custom_field( $value, $post ) {
+    return update_post_meta( $post->ID, '_custom_field', sanitize_text_field( $value ) );
+}
+```
+
+### Add Multiple Custom Fields
+
+```php
+<?php
+/**
+ * Add multiple custom fields
+ */
+function my_plugin_add_multiple_fields() {
+    register_rest_field( 'post', 'view_count', array(
+        'get_callback' => function( $post ) {
+            return (int) get_post_meta( $post['id'], 'views', true );
+        },
+        'schema'       => array(
+            'description' => __( 'Number of views', 'my-plugin' ),
+            'type'        => 'integer',
+        ),
+    ) );
+
+    register_rest_field( 'post', 'reading_time', array(
+        'get_callback' => function( $post ) {
+            $content = get_post_field( 'post_content', $post['id'] );
+            $word_count = str_word_count( strip_tags( $content ) );
+            return ceil( $word_count / 200 ); // Assume 200 words per minute
+        },
+        'schema'       => array(
+            'description' => __( 'Estimated reading time in minutes', 'my-plugin' ),
+            'type'        => 'integer',
+        ),
+    ) );
+}
+add_action( 'rest_api_init', 'my_plugin_add_multiple_fields' );
+```
+
+### Modify Response Data
+
+```php
+<?php
+/**
+ * Modify post response
+ */
+function my_plugin_modify_post_response( $response, $post, $request ) {
+    $data = $response->get_data();
+
+    // Add custom data
+    $data['custom_data'] = array(
+        'views'        => get_post_meta( $post->ID, 'views', true ),
+        'likes'        => get_post_meta( $post->ID, 'likes', true ),
+        'is_featured'  => (bool) get_post_meta( $post->ID, 'featured', true ),
+    );
+
+    // Remove sensitive data
+    unset( $data['author'] );
+
+    $response->set_data( $data );
+
+    return $response;
+}
+add_filter( 'rest_prepare_post', 'my_plugin_modify_post_response', 10, 3 );
+```
+
+---
+
+## Best Practices
+
+### Endpoint Design
+
+1. **Use versioning**: Include version in namespace (`my-plugin/v1`)
+2. **Use nouns for resources**: `/items`, `/users`, not `/get-items`
+3. **Use HTTP methods correctly**: GET (read), POST (create), PUT/PATCH (update), DELETE (delete)
+4. **Use proper status codes**: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 500 (Server Error)
+5. **Return consistent responses**: Use `WP_REST_Response` or `WP_Error`
+
+### Security
+
+1. **Always validate permissions**: Never use `__return_true` for write operations
+2. **Sanitize input**: Use appropriate sanitization callbacks
+3. **Validate input**: Use validation callbacks and schema
+4. **Escape output**: Use `esc_html()`, `esc_url()`, etc.
+5. **Use nonces for admin**: For admin-ajax.php endpoints (not REST API)
+6. **Rate limiting**: Consider implementing rate limiting for public endpoints
+
+### Performance
+
+1. **Limit query results**: Set maximum `per_page` value
+2. **Use pagination**: Always paginate large result sets
+3. **Cache responses**: Use transients for expensive queries
+4. **Optimize queries**: Use `WP_Query` efficiently
+5. **Lazy load data**: Don't include unnecessary data in responses
+
+### Documentation
+
+1. **Document endpoints**: Provide clear descriptions
+2. **Document parameters**: Describe all parameters and their types
+3. **Provide examples**: Include example requests and responses
+4. **Use schema**: Define proper schema for validation and documentation
+
+---
+
+## Common Pitfalls
+
+### ❌ DON'T
+
+```php
+// Don't use __return_true for write operations
+register_rest_route( 'my-plugin/v1', '/items', array(
+    'methods'             => 'POST',
+    'callback'            => 'create_item',
+    'permission_callback' => '__return_true', // BAD!
+) );
+
+// Don't forget to sanitize input
+function create_item( $request ) {
+    $title = $request['title']; // BAD! Not sanitized
+    wp_insert_post( array( 'post_title' => $title ) );
+}
+
+// Don't return raw data
+function get_item( $request ) {
+    return get_post( $request['id'] ); // BAD! Returns WP_Post object
+}
+
+// Don't forget error handling
+function get_item( $request ) {
+    $item = get_post( $request['id'] );
+    return new WP_REST_Response( $item, 200 ); // BAD! No error check
+}
+```
+
+### ✅ DO
+
+```php
+// Use proper permission checks
+register_rest_route( 'my-plugin/v1', '/items', array(
+    'methods'             => 'POST',
+    'callback'            => 'create_item',
+    'permission_callback' => 'check_create_permission', // GOOD!
+) );
+
+// Always sanitize input
+function create_item( $request ) {
+    $title = sanitize_text_field( $request['title'] ); // GOOD!
+    wp_insert_post( array( 'post_title' => $title ) );
+}
+
+// Return formatted data
+function get_item( $request ) {
+    $post = get_post( $request['id'] );
+    $data = array(
+        'id'    => $post->ID,
+        'title' => $post->post_title,
+    );
+    return new WP_REST_Response( $data, 200 ); // GOOD!
+}
+
+// Always handle errors
+function get_item( $request ) {
+    $item = get_post( $request['id'] );
+
+    if ( ! $item ) {
+        return new WP_Error( 'not_found', 'Item not found', array( 'status' => 404 ) );
+    }
+
+    return new WP_REST_Response( $item, 200 ); // GOOD!
+}
+```
+