REST API Extensions

Overview

This project extends the standard WordPress REST API by registering a custom namespace: ua/v1. These extensions are designed to provide more performant and structured access to site data that is not natively exposed by the core wp-json/wp/v2 endpoints, specifically tailored for MVP requirements and decoupled front-ends.

Base URL: https://your-domain.com/wp-json/ua/v1

Authentication

All custom endpoints follow the existing WordPress REST API authentication cookie or application password schemes.

• Public Endpoints: Accessible via standard GET requests without headers.
• Protected Endpoints: Require an X-WP-Nonce header for logged-in sessions or an Authorization: Basic <base64> header for external applications.

Endpoint Reference

Get App Configuration

Retrieves global site settings, menu structures, and theme metadata in a single request to minimize round-trips.

• Endpoint: /config
• Method: GET
• Response Type: application/json

Success Response (200 OK):

{
  "site_name": "My WordPress Site",
  "description": "Just another WordPress site",
  "active_modules": ["auth", "analytics", "commerce"],
  "social_links": {
    "twitter": "https://twitter.com/example",
    "github": "https://github.com/UditAkhourii"
  }
}

Extended Post Data

Provides a slimmed-down version of post data specifically formatted for high-performance listing components.

• Endpoint: /posts-summary
• Method: GET
• Query Parameters:
  • limit (int): Number of posts to return (default: 10).
  • category_id (int): Filter by specific category.

Usage Example:

curl -X GET "https://example.com/wp-json/ua/v1/posts-summary?limit=5"

Integration Guide

Consuming with JavaScript (Fetch API)

To use these endpoints within a React or Vue front-end, you can leverage the native fetch API or the @wordpress/api-fetch package.

import apiFetch from '@wordpress/api-fetch';

// Fetching custom config
const getConfig = async () => {
    try {
        const config = await apiFetch({ path: '/ua/v1/config' });
        console.log('Site Config:', config);
    } catch (error) {
        console.error('Failed to fetch config:', error);
    }
};

Registering New Custom Routes

If you are extending this library, use the internal registration wrapper to ensure your endpoints are correctly prefixed and schema-validated.

Note: This is an internal utility used within the plugin bootstrap, but it is the standard way to contribute new routes.

// Standard pattern for adding a route to the 'ua/v1' namespace
add_action('rest_api_init', function () {
    register_rest_route('ua/v1', '/custom-data', [
        'methods'  => 'GET',
        'callback' => 'get_custom_data_callback',
        'permission_callback' => '__return_true',
    ]);
});

Error Handling

The API returns standard HTTP status codes. Errors are returned in the following JSON format:

| Code | Description | | :--- | :--- | | 401 | Unauthorized - Authentication is required or failed. | | 403 | Forbidden - The current user does not have permission. | | 404 | Not Found - The requested resource or endpoint does not exist. | | 500 | Internal Server Error - Unexpected server-side failure. |

Error Response Body:

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": { "status": 403 }
}