Author Events API

A production-ready WordPress REST API plugin for managing author events. Built to enterprise standards: OOP/PHP 8.0+, a dedicated WP_REST_Controller subclass, JSON Schema validation, capability-gated permissions, and a full PHPUnit test suite.

Table of Contents

• Features
• Requirements
• Installation
• Architecture
• API Reference
  • Authentication
  • List Events
  • Get a Single Event
  • Create an Event
  • Update an Event
  • Delete an Event
  • Response Schema
  • Error Responses
• Running Tests
• Roadmap

Features

• Custom Post Type author_event — leverages the full WordPress data layer (meta API, revisions, trash/restore, capabilities)
• Custom Taxonomy event_category — hierarchical, admin-only
• REST API under author-events/v1/events extending WP_REST_Controller
• Full CRUD — GET (collection + single), POST, PUT/PATCH, DELETE
• Date filtering via ?date=YYYY-MM-DD on the collection endpoint
• JSON Schema validation (get_item_schema) — type coercion, required fields, and format checks are handled automatically per endpoint
• Capability guards — every endpoint requires manage_options; unauthenticated requests get 401, authenticated non-admins get 403
• HATEOAS links — self and collection links on every item response
• Pagination headers — X-WP-Total and X-WP-TotalPages on collection responses
• PSR-4 autoloader — no Composer dependency at runtime; switchable to Composer in one line
• 13-case PHPUnit test suite covering auth, CRUD, date filtering, DB verification, and response contract

Requirements

Installation

Via upload

1. Download or clone this repository.
2. Copy the author-events-api/ folder into wp-content/plugins/.
3. Activate the plugin in Plugins → Installed Plugins.

Via Composer (dev environment)

git clone https://github.com/sarfaraz-kazi/CRUD-API-For-Events
composer install

No Composer autoload is required at runtime — the plugin ships its own spl_autoload_register loader.

Architecture

author-events-api/
├── author-events-api.php               ← Entry point: constants + PSR-4 autoloader
├── composer.json
├── phpunit.xml
├── includes/
│   ├── class-plugin.php                ← Singleton bootstrap (wires all hooks)
│   ├── class-cpt-registration.php      ← CPT, taxonomy, and post meta registration
│   └── api/
│       └── class-events-controller.php ← WP_REST_Controller subclass
└── tests/
    ├── bootstrap.php
    └── class-events-controller-test.php

Design decisions

WP_REST_Controller subclass, not procedural callbacks get_endpoint_args_for_item_schema() reads the JSON Schema once and auto-generates the args array for every route — type coercion, sanitisation, and required validation included. filter_response_by_context() strips fields per context (view / edit / embed) without any per-endpoint logic.

CPT storage over a custom table The WordPress data layer provides meta API, WP_Query with meta_query / tax_query, revisions, trash/restore, and capability maps out of the box. A custom table is warranted only when query patterns outgrow what WP_Query can express efficiently — unnecessary complexity for an MVP.

Separate entry point and Plugin class author-events-api.php only defines constants and registers the autoloader. All hook wiring lives in Plugin::get_instance(), so every component can be instantiated in isolation during tests without bootstrapping the whole plugin.

CHAR type in meta_query BETWEEN Dates are stored as ISO 8601 (YYYY-MM-DDTHH:MM:SS). MySQL's DATETIME type expects a space separator; CHAR keeps the comparison lexicographic, which is correct because ISO 8601 dates sort identically to their chronological order when zero-padded.

API Reference

Authentication

All endpoints require the current user to have the manage_options capability (WordPress Administrators by default). Authenticate using WordPress Application Passwords or cookie-based auth with a valid nonce.

Authorization: Basic base64(username:application-password)

GET /events

Returns a paginated list of events, ordered by start_date ascending.

Query parameters

Example request

curl -u admin:app-password \
  "https://example.com/wp-json/author-events/v1/events?date=2025-06-15&per_page=5"

Example response 200 OK

[
  {
    "id": 42,
    "title": "Book Launch: The Digital Age",
    "description": "<p>Join us for the official launch...</p>",
    "category": "book-launch",
    "start_date": "2025-06-15T09:00:00",
    "end_date": "2025-06-15T11:00:00",
    "status": "publish",
    "date_created": "2025-05-01T12:00:00",
    "date_modified": "2025-05-10T08:30:00",
    "_links": {
      "self":       [{ "href": "https://example.com/wp-json/author-events/v1/events/42" }],
      "collection": [{ "href": "https://example.com/wp-json/author-events/v1/events" }]
    }
  }
]

Response headers

X-WP-Total: 12
X-WP-TotalPages: 3

GET /events/{id}

Returns a single event by its WordPress post ID.

curl -u admin:app-password \
  "https://example.com/wp-json/author-events/v1/events/42"

POST /events

Creates a new event.

Request body (JSON)

Example request

curl -u admin:app-password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "title":       "Annual Author Summit",
    "description": "<p>Gathering of published authors.</p>",
    "category":    "summit",
    "start_date":  "2025-09-10T09:00:00",
    "end_date":    "2025-09-10T17:00:00"
  }' \
  "https://example.com/wp-json/author-events/v1/events"

Response 201 Created — returns the created event with a Location header pointing to the new resource.

PUT/PATCH /events/{id}

Updates an existing event. PUT expects all writeable fields; PATCH accepts any subset.

curl -u admin:app-password \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title", "start_date": "2025-09-10T10:00:00", "end_date": "2025-09-10T18:00:00" }' \
  "https://example.com/wp-json/author-events/v1/events/42"

Response 200 OK — returns the full updated event object.

DELETE /events/{id}

Moves the event to the WordPress trash by default. Pass ?force=true to permanently delete.

# Move to trash
curl -u admin:app-password -X DELETE \
  "https://example.com/wp-json/author-events/v1/events/42"

# Permanent delete
curl -u admin:app-password -X DELETE \
  "https://example.com/wp-json/author-events/v1/events/42?force=true"

Response 200 OK

{
  "deleted": true,
  "previous": { "id": 42, "title": "Annual Author Summit", "..." : "..." }
}

Response Schema

Every event item conforms to the following shape. Fields marked readonly are never accepted on write.

Error Responses

All errors follow the standard WordPress REST error envelope:

{
  "code":    "rest_invalid_param",
  "message": "end_date must be on or after start_date.",
  "data":    { "status": 400 }
}

Running Tests

1. Install the WordPress test library

# Creates a test DB and downloads the WP test suite into /tmp/wordpress-tests-lib
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest

2. Install dev dependencies

composer install

3. Run the suite

WP_TESTS_DIR=/tmp/wordpress-tests-lib vendor/bin/phpunit

With coverage report:

WP_TESTS_DIR=/tmp/wordpress-tests-lib vendor/bin/phpunit --coverage-html=coverage/

Test groups

Roadmap

License

GPL v2 or later — see LICENSE.