DEV Community: KAZI

Building a Custom REST API in WordPress the Right Way

KAZI — Sat, 22 Aug 2026 19:00:00 +0000

WordPress is often treated as a traditional CMS, but its REST API makes it possible to use WordPress as the backend for applications, dashboards, mobile clients, automation systems, and external services.

The difficult part isn't registering an endpoint.

The difficult part is designing the endpoint so that authentication, authorization, validation, error handling, and data access are all handled correctly.

A production API needs a contract.

It needs to know:

Who can access it
What data they can access
What input is accepted
What output is returned
What happens when something fails

Here's a practical approach.

Register a Custom Route

A basic WordPress REST API route can be registered with register_rest_route().

add_action('rest_api_init', function () {
    register_rest_route('myplugin/v1', '/posts', [
        'methods'  => WP_REST_Server::READABLE,
        'callback' => 'myplugin_get_posts',
    ]);
});

This creates an endpoint similar to:

/wp-json/myplugin/v1/posts

The namespace matters.

Using:

myplugin/v1

gives the API a version boundary.

If the response structure changes later, a new version can be introduced without immediately breaking existing clients.

Don't Put Authorization Inside the Callback

A common beginner implementation does everything inside the callback:

function myplugin_get_posts() {

    if (!current_user_can('manage_options')) {
        return new WP_Error(
            'forbidden',
            'Access denied',
            ['status' => 403]
        );
    }

    // Query data...
}

This works, but WordPress provides a cleaner place for the permission decision.

Use permission_callback.

register_rest_route('myplugin/v1', '/posts', [
    'methods'             => WP_REST_Server::READABLE,
    'callback'            => 'myplugin_get_posts',
    'permission_callback' => function () {
        return current_user_can('manage_options');
    },
]);

Now the endpoint has a clearer separation:

Request
   ↓
Permission check
   ↓
Callback
   ↓
Data

That separation becomes increasingly valuable as an API grows.

Authentication Is Not Authorization

These concepts are easy to mix up.

Authentication asks:

Who are you?

Authorization asks:

Are you allowed to perform this operation?

A valid authenticated user should not automatically receive access to every endpoint.

For example:

Authenticated user
      ↓
Role
      ↓
Capability
      ↓
Resource ownership
      ↓
Allowed operation

The permission decision should reflect the actual operation.

A user might be allowed to read a resource but not delete it.

Validate Input

Never assume API input is valid.

Suppose an endpoint accepts:

?page=2
&per_page=20

Validate the values.

$page = absint($request->get_param('page'));

$per_page = absint(
    $request->get_param('per_page')
);

$page = max(1, $page);
$per_page = min(100, max(1, $per_page));

This does two useful things.

It converts input into an expected type.

It also places an upper limit on the amount of data requested.

Without limits, a client could request an unreasonable number of records.

Sanitization and Validation Are Different

These terms are often used interchangeably.

They shouldn't be.

Validation asks:

Is this value acceptable?

Sanitization asks:

Can this value be safely normalized for its intended use?

For example, an email address can be validated:

$email = sanitize_email(
    $request->get_param('email')
);

if (!is_email($email)) {
    return new WP_Error(
        'invalid_email',
        'A valid email address is required',
        ['status' => 400]
    );
}

The exact approach depends on the data type and where the value will be used.

Don't Trust IDs

Suppose the endpoint receives:

/post?id=123

Don't assume post 123 is something the current user should access.

The endpoint should check:

$post_id = absint(
    $request->get_param('id')
);

$post = get_post($post_id);

if (!$post) {
    return new WP_Error(
        'not_found',
        'Post not found',
        ['status' => 404]
    );
}

Then apply whatever authorization rules the application requires.

The existence of a resource and permission to access it are separate questions.

Return Structured Errors

Avoid returning random strings from different parts of the API.

A consistent error structure makes client-side development much easier.

WordPress provides WP_Error for this purpose.

return new WP_Error(
    'invalid_request',
    'The requested resource is invalid.',
    [
        'status' => 400,
        'field'  => 'id',
    ]
);

Now the client has a machine-readable error code and HTTP status.

That is much better than:

Something went wrong.

Keep the Response Contract Stable

Suppose version one returns:

{
  "id": 123,
  "title": "Example"
}

Then version two suddenly changes it to:

{
  "post_id": 123,
  "name": "Example"
}

Existing clients can break.

API responses should therefore be treated as contracts.

If a breaking change is necessary, version the endpoint.

/myplugin/v1/posts
/myplugin/v2/posts

You don't necessarily need a new version for every small change.

But breaking response changes deserve careful handling.

Don't Return Everything

A database object can contain much more information than the client needs.

Returning everything creates unnecessary coupling.

Instead, build a deliberate response:

return [
    'id'      => $post->ID,
    'title'   => get_the_title($post),
    'url'     => get_permalink($post),
    'excerpt' => get_the_excerpt($post),
];

This gives the client a stable, predictable structure.

It also reduces the amount of data transferred.

Think About Pagination Early

An endpoint that returns ten posts today may return ten thousand posts next year.

Design pagination from the beginning.

A common approach is:

?page=1&per_page=20

Then return metadata that helps the client understand the collection.

For example:

{
  "items": [],
  "page": 1,
  "per_page": 20,
  "total": 240
}

The exact response design depends on the client.

The important thing is avoiding an endpoint whose response size grows without a limit.

Cache Expensive API Responses

If an endpoint repeatedly performs an expensive query, caching can help.

WordPress transients can work for many cases:

$cache_key = 'myplugin_posts_page_1';

$data = get_transient($cache_key);

if (false === $data) {
    $data = expensive_query();

    set_transient(
        $cache_key,
        $data,
        HOUR_IN_SECONDS
    );
}

return $data;

Caching strategy depends on how frequently the underlying data changes.

Don't cache everything automatically.

Cache data where repeated computation is actually expensive.

Log Failures, Not Sensitive Data

Logs are useful when debugging API failures.

But logging entire requests can accidentally expose credentials, tokens, cookies, or personal information.

A better log entry might contain:

Request ID
Endpoint
HTTP method
User ID
Status code
Execution time
Error code

Avoid dumping complete authorization headers or sensitive request payloads into logs.

Debugging data should help diagnose the problem without creating another security problem.

Design for Failure

External API consumers will send unexpected requests.

Networks will fail.

Database queries will fail.

Permissions will be wrong.

Third-party services will time out.

A good API expects failure.

For each endpoint, define:

Success
Invalid input
Unauthenticated
Unauthorized
Not found
Rate limited
Server error
External dependency failure

This makes both the backend and client more predictable.

A Practical Endpoint Architecture

For a larger plugin, I like thinking about an endpoint in layers:

REST Route
    ↓
Permission Callback
    ↓
Input Validation
    ↓
Service Layer
    ↓
Repository / WordPress Data
    ↓
Response Transformer
    ↓
REST Response

The exact architecture can be simpler for small plugins.

But the separation becomes valuable as functionality grows.

It prevents the REST callback from turning into a 500-line function that handles authentication, database queries, external APIs, formatting, and error handling all at once.

The Real Goal

A REST API isn't successful because its endpoint returns JSON.

It is successful when another application can depend on that endpoint without needing to understand the internal implementation.

That means:

Clear routes
Stable contracts
Explicit permissions
Validated input
Predictable errors
Controlled response sizes
Sensible caching
Useful logging
Versioning where necessary

Once those pieces are in place, WordPress becomes much more than a content management system.

It becomes a capable application backend.

Advanced WordPress Performance Optimization: A Developer's Guide

KAZI — Fri, 21 Aug 2026 18:53:05 +0000

WordPress performance problems are rarely caused by one thing.

A slow site might have an inefficient database query, excessive JavaScript, a poorly configured cache, slow third-party APIs, expensive PHP execution, or a combination of several smaller problems.

That is why blindly installing another caching plugin is often the wrong first move.

Performance work should start with measurement.

This guide looks at WordPress performance from the developer's perspective, from the server and PHP layer through database queries, assets, caching, and external services.

Start With the Request Lifecycle

Before optimizing anything, understand what happens when a visitor requests a WordPress page.

A simplified request looks like this:

Browser
   ↓
DNS
   ↓
Web Server
   ↓
PHP
   ↓
WordPress Bootstrap
   ↓
Plugins
   ↓
Theme
   ↓
Database
   ↓
HTML Response
   ↓
Browser
   ↓
CSS / JS / Images

There are multiple places where latency can appear.

If the server takes 800 ms before sending the first byte, optimizing a 200 KB image won't solve the primary problem.

If PHP responds quickly but the browser spends three seconds executing JavaScript, server optimization alone won't fix the experience.

Performance optimization is therefore a diagnosis problem.

Measure Before Changing Code

A useful baseline should include more than a single performance score.

Look at:

Time to First Byte
Largest Contentful Paint
Interaction to Next Paint
Cumulative Layout Shift
Total Blocking Time
Database query time
PHP execution time
Number of HTTP requests
JavaScript execution
Image size

A score can tell you that something is wrong.

It doesn't necessarily tell you why.

For server-side debugging, tools such as Query Monitor can expose database queries, hooks, HTTP requests, PHP errors, and other information directly inside WordPress.

That is much more useful than changing five settings and hoping the score improves.

PHP Is Often the First Hidden Bottleneck

WordPress plugins can add significant work to every request.

Consider this pattern:

add_action('init', function () {
    $posts = get_posts([
        'numberposts' => -1,
        'post_type'   => 'post',
    ]);

    // Process every post...
});

The code may work perfectly on a development site.

It becomes a problem when the site contains thousands of posts.

Loading large datasets on every request increases memory usage and execution time.

The better question is:

Does this operation really need to run during every request?

Often the answer is no.

Move Expensive Work Out of the Request

Suppose a plugin needs to scan 10,000 posts.

Doing that during a visitor's HTTP request is a bad design.

Instead:

Visitor request
      ↓
Fast response

Background job
      ↓
Process 100 records
      ↓
Save state
      ↓
Process next batch

Batch processing is especially useful for:

Content analysis
Link scanning
Product monitoring
Large database migrations
API synchronization
SEO audits
Image processing

The user should not have to wait for work that doesn't affect the current page.

WordPress Cron Has Limits

WP-Cron is useful, but it isn't a traditional system cron.

By default, WordPress schedules cron execution based on site traffic.

That means a low-traffic site may not execute scheduled tasks exactly when expected.

For important background jobs, a real server-side cron can provide more predictable execution.

For example:

Server Cron
     ↓
wp-cron.php
     ↓
WordPress scheduled tasks

The exact setup depends on the hosting environment.

The important architectural idea is separating scheduled processing from normal page requests.

Database Queries Need Attention

One of the easiest ways to create a slow WordPress site is to make the database do unnecessary work.

For example:

$posts = new WP_Query([
    'post_type'      => 'post',
    'posts_per_page' => -1,
]);

Loading every matching post may be fine for a small dataset.

It becomes expensive as the database grows.

Pagination, targeted queries, indexed fields, and smaller datasets can make a substantial difference.

Also watch for queries inside loops.

This pattern deserves suspicion:

foreach ($posts as $post) {
    $value = get_post_meta($post->ID, 'some_key', true);
}

It may generate more database work than expected.

The correct optimization depends on the actual query behavior, which is why profiling matters.

Object Caching Is Different From Page Caching

These two are often mixed together.

Page caching stores generated responses.

Object caching stores frequently requested data.

For example:

Page Cache
Request → HTML

Object Cache
WordPress → Cached database/object result

They solve different problems.

A page cache can eliminate much of the PHP work for anonymous visitors.

Object caching can reduce repeated database operations when WordPress still needs to execute PHP.

Both can be useful.

Neither replaces good application code.

External APIs Can Destroy Performance

Modern WordPress plugins often communicate with external services.

Amazon APIs.

AI providers.

Analytics systems.

Payment services.

Image generation APIs.

Search APIs.

A remote request can easily become the slowest part of a WordPress operation.

Never make an unnecessary external API request during the visitor's page request.

Instead, cache the result whenever possible.

$data = get_transient('remote_data');

if (false === $data) {
    $data = fetch_remote_data();

    set_transient(
        'remote_data',
        $data,
        HOUR_IN_SECONDS
    );
}

Now the external service doesn't have to be contacted on every request.

Be Careful With JavaScript

A page can have a fast PHP response and still feel slow.

Large JavaScript bundles can block rendering or delay interaction.

Audit:

Bundle size
Third-party scripts
Unused JavaScript
Script loading order
Long-running event handlers
DOM manipulation
Analytics scripts

WordPress developers should also avoid loading plugin assets globally when they are only needed on specific screens.

Instead of:

wp_enqueue_script('my-plugin-script');

on every page, conditionally load assets where possible.

For example:

if (is_singular('product')) {
    wp_enqueue_script('my-product-script');
}

The exact condition depends on the application.

Images Still Matter

Images remain one of the easiest performance wins.

Use:

Appropriate dimensions
Modern formats where supported
Responsive images
Lazy loading where appropriate
Compression
Correct aspect ratios

But don't blindly compress everything.

A 40 KB icon and a 2 MB hero image are different problems.

Measure the largest assets first.

Don't Ignore Third-Party Scripts

A website may contain:

Analytics
Advertising
Chat
Heatmaps
Social widgets
Affiliate widgets
Tracking

Every external dependency has a cost.

You don't fully control the response time of a third-party server.

That means third-party scripts should be treated as dependencies with performance consequences.

Load them only where they provide enough value to justify their cost.

Build a Performance Budget

A useful development practice is to define limits.

For example:

Initial JavaScript:      < X KB
Hero image:              < X KB
External requests:       < X
Database queries:        < X
Server response:         < X ms

The exact values depend on the project.

The point is to stop performance from becoming a vague goal.

Once there is a budget, regressions become measurable.

Optimize One Layer at a Time

A common mistake is changing everything simultaneously.

Install a cache plugin.

Change the CDN.

Minify everything.

Optimize the database.

Remove plugins.

Change the theme.

Then run the test again.

If performance improves, you don't know which change helped.

A better workflow is:

Measure
  ↓
Identify bottleneck
  ↓
Change one variable
  ↓
Measure again
  ↓
Keep or revert

This is slower for the first hour.

It is much faster when debugging a complex site.

The Developer's Rule

Don't optimize what you haven't measured.

A slow WordPress site is not a single problem.

It is a chain of components.

Find the slow component.

Measure it.

Fix it.

Measure again.

Then move to the next bottleneck.

That mindset is more valuable than any particular caching configuration because the underlying architecture changes from project to project.