Linchpin Blocks REST API Endpoints

This document describes the REST API endpoints available for the Linchpin Blocks plugin.

Settings Endpoints

GET /wp-json/linchpin-blocks/v1/settings

Retrieves the current plugin settings.

Authentication: Requires manage_options capability

Response:

{
  "disabled_blocks": [],
  "features": {
    "enable_animations": false
  }
}

POST /wp-json/linchpin-blocks/v1/settings

Updates plugin settings.

Authentication: Requires manage_options capability

Request Body:

{
  "disabled_blocks": ["linchpin-blocks/example-block"],
  "features": {
    "enable_animations": true
  }
}

Reset Functionality: To reset all settings to defaults:

{
  "reset": "all"
}

To reset a specific section:

{
  "reset": "features"
}

Block Guides Endpoints

POST /wp-json/linchpin-blocks/v1/block-guides/dismiss

Dismisses a block guide for the current user.

Authentication: Requires edit_posts capability

Request Body:

{
  "block_name": "linchpin-blocks/animation"
}

GET /wp-json/linchpin-blocks/v1/block-guides/status

Gets the dismissal status of a block guide for the current user.

Authentication: Requires edit_posts capability

Query Parameters:

• block_name (required): The name of the block to check

Response:

{
  "block": "linchpin-blocks/animation",
  "isDismissed": false,
  "metaExists": false,
  "debug": {
    "userId": 1,
    "meta": null
  }
}

Usage Examples

JavaScript (Frontend)

// Get settings
const response = await fetch('/wp-json/linchpin-blocks/v1/settings', {
  headers: {
    'X-WP-Nonce': wpApiSettings.nonce
  }
});
const settings = await response.json();

// Update settings
const updateResponse = await fetch('/wp-json/linchpin-blocks/v1/settings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-WP-Nonce': wpApiSettings.nonce
  },
  body: JSON.stringify({
    features: {
      enable_animations: true
    }
  })
});

PHP (Backend)

// Get settings
$response = wp_remote_get(rest_url('linchpin-blocks/v1/settings'));
$settings = json_decode(wp_remote_retrieve_body($response), true);

// Update settings
$response = wp_remote_post(rest_url('linchpin-blocks/v1/settings'), [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-WP-Nonce' => wp_create_nonce('wp_rest')
    ],
    'body' => json_encode([
        'features' => [
            'enable_animations' => true
        ]
    ])
]);

Error Handling

All endpoints return appropriate HTTP status codes:

• 200: Success
• 400: Bad Request (invalid parameters)
• 401: Unauthorized (insufficient permissions)
• 404: Not Found (settings not found)
• 500: Internal Server Error

Error responses include a message and status code:

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