OBY REST CRUD

A unified WordPress REST API plugin that provides full CRUD operations for both Items and Todos. This plugin creates custom database tables and exposes RESTful endpoints under a single namespace.

Features

• Object-Oriented Design: Refactored to use a singleton class for better organization and extensibility
• Dual Resource Support: Manage both menu items and todo tasks in one plugin
• Full CRUD Operations: Create, Read, Update, and Delete for both resources
• RESTful API: Clean, standard REST endpoints under oby-crud/v1 namespace
• Authentication Control: Public read access, admin-only write operations (filterable via orc_required_capability)
• Pagination & Filtering: List endpoints support search, filtering, sorting, and pagination
• Sorting Support: Sort by any allowed field in ascending or descending order
• Enhanced Search: Todos can be searched by title or description
• Timestamps: Tracks both created_at and updated_at for all records
• Automatic Table Creation: Custom tables are created on plugin activation with sample data
• Convenience Routes: Quick action to mark todos as complete
• REST Schema: Routes include JSON schema for better API documentation and validation
• Clean Uninstall: Tables are removed when the plugin is deleted

Installation

1. Copy the oby-rest-crud.php and uninstall.php files to your WordPress plugins directory (wp-content/plugins/oby-rest-crud/)
2. Activate the plugin from the WordPress admin panel
3. The plugin will automatically create two tables:
   • wp_rest_items - for items/products
   • wp_oby_todos - for todos/tasks
4. Sample data will be inserted if tables are empty

API Endpoints

Base URL: https://your-site.com/wp-json/oby-crud/v1

Items Endpoints

Query Parameters for GET /items

• search (string, optional) - Search items by name
• page (integer, optional, default: 1) - Page number
• per_page (integer, optional, default: 10, max: 100) - Items per page
• orderby (string, optional, default: id) - Sort by: id, name, price, status, created_at, updated_at
• order (string, optional, default: desc) - Sort order: asc or desc

Request Body for POST /items

{
  "name": "Product Name",  // Required
  "price": 9.99          // Optional, defaults to 0
}

Request Body for PUT /items/{id}

{
  "name": "Updated Name",    // Optional
  "price": 19.99,           // Optional
  "status": "inactive"      // Optional, values: "active" or "inactive"
}

Response Format:

{
  "items": [...],
  "pagination": {
    "total": 10,
    "total_pages": 1,
    "page": 1,
    "per_page": 10
  }
}

Response Headers:

• X-WP-Total - Total number of items
• X-WP-TotalPages - Total number of pages

Todos Endpoints

Query Parameters for GET /todos

• search (string, optional) - Search todos by title or description
• status (string, optional) - Filter by status: pending or completed
• page (integer, optional, default: 1) - Page number
• per_page (integer, optional, default: 10, max: 100) - Todos per page
• orderby (string, optional, default: id) - Sort by: id, title, status, created_at, updated_at
• order (string, optional, default: desc) - Sort order: asc or desc

Request Body for POST /todos

{
  "title": "Task Title",           // Required
  "description": "Task details",   // Optional, defaults to ""
  "status": "pending"            // Optional, values: "pending" or "completed", defaults to "pending"
}

Request Body for PUT /todos/{id}

{
  "title": "Updated Title",       // Optional
  "description": "New details",   // Optional
  "status": "completed"          // Optional, values: "pending" or "completed"
}

Response Format:

{
  "todos": [...],
  "pagination": {
    "total": 10,
    "total_pages": 1,
    "page": 1,
    "per_page": 10
  }
}

Response Headers:

• X-WP-Total - Total number of todos
• X-WP-TotalPages - Total number of pages

Database Schema

Items Table: wp_rest_items

Todos Table: wp_oby_todos

Usage Examples

Using cURL

List all items (public):

curl https://your-site.com/wp-json/oby-crud/v1/items

List items sorted by price ascending:

curl https://your-site.com/wp-json/oby-crud/v1/items?orderby=price&order=asc

Search todos by title or description:

curl https://your-site.com/wp-json/oby-crud/v1/todos?search=api

Create a new item (admin authentication required):

curl -X POST https://your-site.com/wp-json/oby-crud/v1/items \
  -H "Content-Type: application/json" \
  -u "username:application_password" \
  -d '{"name": "Coffee", "price": 4.50}'

Update a todo:

curl -X PUT https://your-site.com/wp-json/oby-crud/v1/todos/1 \
  -H "Content-Type: application/json" \
  -u "username:application_password" \
  -d '{"status": "completed"}'

Mark todo as complete (shortcut):

curl -X POST https://your-site.com/wp-json/oby-crud/v1/todos/1/complete \
  -u "username:application_password"

Delete an item:

curl -X DELETE https://your-site.com/wp-json/oby-crud/v1/items/2 \
  -u "username:application_password"

Using JavaScript (Fetch API)

// Get all todos with pagination
fetch('https://your-site.com/wp-json/oby-crud/v1/todos?page=1&per_page=5')
  .then(res => res.json())
  .then(data => console.log(data.todos, data.pagination));

// Create a todo (requires authentication)
fetch('https://your-site.com/wp-json/oby-crud/v1/todos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa('username:application_password')
  },
  body: JSON.stringify({
    title: 'New Task',
    description: 'Task description'
  })
})
  .then(res => res.json())
  .then(data => console.log(data));

Authentication

For write operations (POST, PUT, DELETE), the plugin requires users with a capability (by default manage_options, typically administrators). You can authenticate using:

• WordPress Application Passwords (recommended for REST API) - Available in WordPress 5.6+
• Cookie authentication (for logged-in users in the same site)
• Basic Auth (with plugins or in development)

Customizing Permissions

You can change the required capability using the orc_required_capability filter:

add_filter('orc_required_capability', function() {
    return 'edit_posts'; // Allow editors to manage items and todos
});

Error Responses

Example 404 response:

{
  "code": "not_found",
  "message": "Todo not found.",
  "data": {
    "status": 404
  }
}

Notes

• Public GET endpoints allow anyone to read data
• All write operations require the configured capability (default: administrator privileges)
• Partial updates are supported for PUT requests (only sent fields are updated)
• The plugin uses dbDelta() for safe table creation/updates
• Sample data is only inserted if the respective table is empty on activation
• When uninstalling the plugin (deleting), both custom tables will be permanently removed
• Pagination data is returned in both the JSON body and response headers for flexibility
• Todos can be searched across both title and description fields

Changelog

Version 1.1.0

• OOP Refactor: Converted to singleton class-based architecture
• Sorting: Added orderby and order parameters to list endpoints
• Enhanced Pagination: Pagination metadata now included in JSON response body
• Timestamps: Added updated_at field to both tables
• Extended Search: Todos now searchable by title and description
• REST Schema: Added JSON schema for routes
• Capability Filter: Added orc_required_capability filter for flexible permissions
• Uninstall Support: Added uninstall.php to clean up tables on deletion

Version 1.0.0

• Unified both OBY REST Practice and OBY Todo plugins into single plugin
• Combined namespaces under oby-crud/v1
• Added support for both items and todos
• Comprehensive documentation