Vengala Vinay

Having 12+ Years of Experience in Software Development

Home » How to implement custom Heartbeat API endpoints with token authentication in Gutenberg blocks

How to implement custom Heartbeat API endpoints with token authentication in Gutenberg blocks

Leveraging WordPress REST API for Real-time Data Synchronization in Gutenberg

For e-commerce platforms built on WordPress, real-time data synchronization is paramount. This often involves dynamic updates to product availability, inventory levels, or order statuses directly within the Gutenberg editor, providing content creators with immediate feedback and reducing manual intervention. While WordPress’s REST API offers a robust foundation, custom endpoints with secure authentication are frequently required to handle specific e-commerce workflows. This guide details the implementation of custom Heartbeat API endpoints, secured with token authentication, to facilitate such dynamic interactions.

Registering Custom REST API Endpoints

The first step is to register custom routes within the WordPress REST API. This is achieved using the register_rest_route function, typically within a plugin’s main file or an `functions.php` file. We’ll define a route for fetching product data, which will be accessed by our Gutenberg block.

Endpoint for Product Data Retrieval

Let’s create an endpoint at /my-ecommerce/v1/products that accepts a product ID and returns its details. This endpoint will be accessible via a GET request.

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-ecommerce/v1', '/products/(?P<id>\d+)', array(
        'methods' => 'GET',
        'callback' => 'my_ecommerce_get_product_data',
        'permission_callback' => '__return_true', // Placeholder for actual permission check
        'args' => array(
            'id' => array(
                'validate_callback' => function( $param, $request, $key ) {
                    return is_numeric( $param );
                }
            ),
        ),
    ) );
} );

function my_ecommerce_get_product_data( WP_REST_Request $request ) {
    $product_id = $request->get_param( 'id' );

    if ( ! $product_id ) {
        return new WP_Error( 'rest_invalid_param', esc_html__( 'Product ID is required.', 'my-ecommerce' ), array( 'status' => 400 ) );
    }

    $product = wc_get_product( $product_id );

    if ( ! $product ) {
        return new WP_Error( 'rest_not_found', esc_html__( 'Product not found.', 'my-ecommerce' ), array( 'status' => 404 ) );
    }

    // Prepare product data for REST API response
    $data = array(
        'id' => $product->get_id(),
        'name' => $product->get_name(),
        'price' => $product->get_price(),
        'stock_status' => $product->get_stock_status(),
        'stock_quantity' => $product->get_stock_quantity(),
    );

    return new WP_REST_Response( $data, 200 );
}

In this snippet:

  • We hook into rest_api_init to register our route.
  • The route my-ecommerce/v1/products/(?P<id>\d+) defines a namespace, version, and a dynamic parameter for the product ID.
  • methods specifies the HTTP method (GET).
  • callback points to our function my_ecommerce_get_product_data.
  • permission_callback is set to __return_true for now; we’ll address authentication later.
  • args defines validation for the ‘id’ parameter.
  • The callback function retrieves the product ID, fetches the WooCommerce product object, and returns a structured JSON response.

Implementing Token-Based Authentication

Directly exposing API endpoints without authentication is a security risk. For Gutenberg blocks, especially those interacting with sensitive e-commerce data, token-based authentication is a robust solution. This involves generating a unique token for each user or session and verifying it with each API request.

Generating and Storing Authentication Tokens

We can leverage WordPress’s user meta to store authentication tokens. A simple approach is to generate a random string and associate it with the logged-in user. This token can be passed in the request headers.

/**
 * Generates a secure authentication token.
 *
 * @return string
 */
function my_ecommerce_generate_auth_token() {
    return bin2hex( random_bytes( 32 ) ); // Generates a 64-character hex token
}

/**
 * Gets or generates an authentication token for the current user.
 *
 * @return string|false The token, or false if user is not logged in.
 */
function my_ecommerce_get_user_auth_token() {
    if ( ! is_user_logged_in() ) {
        return false;
    }
    $user_id = get_current_user_id();
    $token = get_user_meta( $user_id, '_my_ecommerce_auth_token', true );

    if ( empty( $token ) ) {
        $token = my_ecommerce_generate_auth_token();
        update_user_meta( $user_id, '_my_ecommerce_auth_token', $token );
    }
    return $token;
}

/**
 * Registers a REST API endpoint to retrieve the user's auth token.
 */
add_action( 'rest_api_init', function () {
    register_rest_route( 'my-ecommerce/v1', '/auth/token', array(
        'methods' => 'GET',
        'callback' => 'my_ecommerce_handle_get_auth_token',
        'permission_callback' => function() {
            return is_user_logged_in(); // Ensure user is logged in
        },
    ) );
} );

function my_ecommerce_handle_get_auth_token( WP_REST_Request $request ) {
    $token = my_ecommerce_get_user_auth_token();
    if ( $token ) {
        return new WP_REST_Response( array( 'token' => $token ), 200 );
    } else {
        return new WP_Error( 'rest_not_authenticated', esc_html__( 'User not authenticated.', 'my-ecommerce' ), array( 'status' => 401 ) );
    }
}

This code:

  • Introduces my_ecommerce_generate_auth_token for secure token creation.
  • my_ecommerce_get_user_auth_token retrieves an existing token or generates a new one, storing it in user meta.
  • A new endpoint /my-ecommerce/v1/auth/token is registered to allow authenticated users to fetch their token.
  • The permission_callback for the token endpoint ensures only logged-in users can access it.

Securing Custom Endpoints with the Token

Now, we need to modify our product data endpoint to verify the authentication token. We’ll add a custom permission_callback that checks for a specific header (e.g., X-Auth-Token) and validates its value against the stored user token.

add_action( 'rest_api_init', function () {
    // ... (previous route registration for /products/{id}) ...

    register_rest_route( 'my-ecommerce/v1', '/products/(?P<id>\d+)', array(
        'methods' => 'GET',
        'callback' => 'my_ecommerce_get_product_data',
        'permission_callback' => 'my_ecommerce_verify_auth_token', // Use our custom permission callback
        'args' => array(
            'id' => array(
                'validate_callback' => function( $param, $request, $key ) {
                    return is_numeric( $param );
                }
            ),
        ),
    ) );
} );

/**
 * Verifies the authentication token from the request header.
 *
 * @param WP_REST_Request $request The current request object.
 * @return bool|WP_Error True if authenticated, WP_Error otherwise.
 */
function my_ecommerce_verify_auth_token( WP_REST_Request $request ) {
    $token_header = $request->get_header( 'X-Auth-Token' );

    if ( ! $token_header ) {
        return new WP_Error( 'rest_auth_error', esc_html__( 'Authentication token is missing.', 'my-ecommerce' ), array( 'status' => 401 ) );
    }

    // Attempt to find the user associated with this token
    global $wpdb;
    $user_id = $wpdb->get_var( $wpdb->prepare( "SELECT user_id FROM {$wpdb}'_usermeta' WHERE meta_key = '_my_ecommerce_auth_token' AND meta_value = %s", $token_header ) );

    if ( ! $user_id ) {
        return new WP_Error( 'rest_auth_error', esc_html__( 'Invalid authentication token.', 'my-ecommerce' ), array( 'status' => 401 ) );
    }

    // Optionally, you might want to check if the user is still active or has specific capabilities.
    // For simplicity, we'll just check if the user exists.
    if ( ! get_user_by( 'id', $user_id ) ) {
        return new WP_Error( 'rest_auth_error', esc_html__( 'User associated with token not found.', 'my-ecommerce' ), array( 'status' => 401 ) );
    }

    // Set the current user for the request context if needed by other parts of the callback
    wp_set_current_user( $user_id );

    return true; // Authentication successful
}

Key aspects of my_ecommerce_verify_auth_token:

  • It retrieves the X-Auth-Token header from the incoming request.
  • If the header is missing, it returns a 401 Unauthorized error.
  • It queries the wp_usermeta table directly to find the user_id associated with the provided token. This is more efficient than iterating through all users.
  • If no user is found for the token, or if the user no longer exists, it returns a 401 error.
  • Upon successful verification, it optionally sets the current user using wp_set_current_user, which can be useful if your callback logic depends on the current user’s context.
  • It returns true to indicate that the request is authorized.

Integrating with Gutenberg Blocks

To utilize these custom endpoints within a Gutenberg block, you’ll need to make JavaScript API calls from your block’s editor component. This typically involves fetching the authentication token first, then using it in subsequent requests to your custom endpoints.

Fetching the Auth Token in JavaScript

Before making any authenticated requests, your block’s JavaScript needs to obtain the user’s authentication token. This can be done by calling the /my-ecommerce/v1/auth/token endpoint.

// Assuming you have a way to get the nonce for the REST API
// For example, using wp_localize_script to pass data from PHP to JS

const restApiUrl = '/wp-json/my-ecommerce/v1/auth/token';

async function getAuthToken() {
    try {
        const response = await fetch(restApiUrl, {
            method: 'GET',
            headers: {
                'X-WP-Nonce': wpApiSettings.nonce, // Use WordPress REST API nonce for initial authentication
            },
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        return data.token;
    } catch (error) {
        console.error("Error fetching auth token:", error);
        return null;
    }
}

Note the use of X-WP-Nonce for the initial request to fetch the token. This leverages WordPress’s built-in nonce verification for authenticated REST API requests. Once you have the token, you’ll use it in the X-Auth-Token header for subsequent calls.

Making Authenticated Requests from the Block

Once you have the token, you can use it to fetch product data. This example shows how to integrate this into a Gutenberg block’s edit function, perhaps to display product details dynamically.

import { registerBlockType } from '@wordpress/blocks';
import { useState, useEffect } from '@wordpress/element';
import { __ } from '@wordpress/i18n';
import apiFetch from '@wordpress/api-fetch'; // A more robust way to interact with WP REST API

// Assuming wpApiSettings is localized from PHP with nonce
const { wpApiSettings } = window;

// Helper function to get auth token (as defined above)
async function getAuthToken() {
    try {
        const response = await apiFetch({
            path: '/my-ecommerce/v1/auth/token',
            method: 'GET',
            headers: {
                'X-WP-Nonce': wpApiSettings.nonce,
            },
        });
        return response.token;
    } catch (error) {
        console.error("Error fetching auth token:", error);
        return null;
    }
}

// Helper function to fetch product data
async function fetchProductData(productId, authToken) {
    try {
        const response = await apiFetch({
            path: `/my-ecommerce/v1/products/${productId}`,
            method: 'GET',
            headers: {
                'X-Auth-Token': authToken,
            },
        });
        return response;
    } catch (error) {
        console.error("Error fetching product data:", error);
        return null;
    }
}

registerBlockType('my-ecommerce/product-display', {
    title: __('Product Display', 'my-ecommerce'),
    icon: 'cart',
    category: 'ecommerce',
    attributes: {
        productId: {
            type: 'string',
            default: '',
        },
    },
    edit: (props) => {
        const { attributes, setAttributes } = props;
        const [productDetails, setProductDetails] = useState(null);
        const [loading, setLoading] = useState(false);
        const [error, setError] = useState(null);

        useEffect(() => {
            const loadProduct = async () => {
                if (!attributes.productId) {
                    setProductDetails(null);
                    setError(null);
                    return;
                }

                setLoading(true);
                setError(null);

                const token = await getAuthToken();
                if (!token) {
                    setError(__('Could not authenticate. Please log in.', 'my-ecommerce'));
                    setLoading(false);
                    return;
                }

                const data = await fetchProductData(attributes.productId, token);
                if (data) {
                    setProductDetails(data);
                } else {
                    setError(__('Failed to load product data.', 'my-ecommerce'));
                }
                setLoading(false);
            };

            loadProduct();
        }, [attributes.productId]); // Re-run when productId changes

        return (
            <div className="my-ecommerce-product-block">
                <h3>{__('Product Display', 'my-ecommerce')}</h3>
                <label htmlFor="product-id-input">{__('Product ID:', 'my-ecommerce')}</label>
                <input
                    id="product-id-input"
                    type="text"
                    value={attributes.productId}
                    onChange={(e) => setAttributes({ productId: e.target.value })}
                    placeholder={__('Enter Product ID', 'my-ecommerce')}
                />

                {loading && <p>{__('Loading...', 'my-ecommerce')}</p>}
                {error && <p style={{ color: 'red' }}>{error}</p>}
                {productDetails && (
                    <div>
                        <p><strong>{__('Name:', 'my-ecommerce')}</strong> {productDetails.name}</p>
                        <p><strong>{__('Price:', 'my-ecommerce')}</strong> {productDetails.price}</p>
                        <p><strong>{__('Stock Status:', 'my-ecommerce')}</strong> {productDetails.stock_status}</p>
                        {productDetails.stock_quantity !== null && (
                            <p><strong>{__('Quantity:', 'my-ecommerce')}</strong> {productDetails.stock_quantity}</p>
                        )}
                    </div>
                )}
            </div>
        );
    },
    save: (props) => {
        // The save function typically renders static HTML or uses a placeholder.
        // Dynamic data should be handled by JavaScript on the frontend if needed.
        // For this example, we'll just show the product ID.
        return (
            <div className="my-ecommerce-product-block-static">
                <p>{__('Product ID:', 'my-ecommerce')} {props.attributes.productId}</p>
                {/* In a real e-commerce scenario, you might fetch and display this dynamically on the frontend */}
            </div>
        );
    },
});

In this JavaScript code:

  • We use @wordpress/api-fetch for making requests to the WordPress REST API, which handles nonces automatically for authenticated endpoints.
  • The useEffect hook in the edit function is triggered when the productId attribute changes.
  • It first calls getAuthToken to retrieve the authentication token.
  • Then, it uses this token to call fetchProductData for the specified product ID.
  • The fetched product details are stored in the productDetails state and displayed in the editor.
  • Error handling is included for token retrieval and data fetching.
  • The save function is kept simple, as dynamic data rendering is usually handled client-side or via server-side rendering for blocks.

Considerations for Production Environments

While the above implementation provides a functional solution, several aspects are crucial for production readiness:

Token Expiration and Refresh

For enhanced security, tokens should have an expiration time. You could store an expiration timestamp along with the token in user meta. The JavaScript would then check this timestamp. If expired, it could attempt to refresh the token (e.g., by making another request to an endpoint that re-authenticates the user or generates a new token based on existing session cookies) or prompt the user to re-authenticate.

Rate Limiting and Security Hardening

Implement rate limiting on your API endpoints to prevent abuse. Consider using a plugin like “WP Rate Limiter” or implementing custom logic within your permission callbacks. Ensure your server environment is secure, and regularly update WordPress core, themes, and plugins.

Error Handling and User Feedback

Provide clear and actionable feedback to users when authentication fails or data cannot be retrieved. This includes informative error messages in the Gutenberg editor and, if applicable, on the frontend.

Alternative Authentication Methods

Depending on your specific needs, other authentication methods might be suitable, such as JWT (JSON Web Tokens) if you have a more complex microservices architecture, or OAuth for third-party integrations. However, for internal Gutenberg block interactions, the token-based approach described here is often sufficient and easier to implement within the WordPress ecosystem.

Conclusion

By implementing custom REST API endpoints with token-based authentication, you can create dynamic and secure interactions within your Gutenberg blocks. This empowers content creators with real-time data and enables sophisticated e-commerce functionalities directly within the WordPress editor, enhancing both user experience and operational efficiency.

Recent Posts

Top Categories

Our Products

Our Services