Adding custom fields to the WordPress REST API makes it easier to access and manage additional data, like author bios, event details, or product specifications, directly from API endpoints. This helps developers streamline workflows, connect WordPress to external systems, and build dynamic applications.
Here’s how you can do it:
- Enable REST API for Custom Post Types: Use the
show_in_restparameter when registering custom post types to make them accessible via the API. - Add Custom Fields to API Responses: Use
register_rest_fieldfor precise control or the Advanced Custom Fields (ACF) plugin for a simpler approach. - Create Custom Endpoints: Use
register_rest_routeto build tailored endpoints for specific data needs. - Secure Your API: Implement
permission_callbackto control access based on user roles and permissions. - Optimize Responses: Reduce payload size with
_fieldsparameters, use pagination, and cache frequent requests for better performance.
Quick Example
Enable REST API for a custom post type:
$args = array( 'public' => true, 'show_in_rest' => true, 'label' => 'Books' ); register_post_type( 'book', $args ); Add a custom field to API responses:
add_action( 'rest_api_init', function() { register_rest_field( 'book', 'author_bio', array( 'get_callback' => function( $post ) { return get_post_meta( $post['id'], 'author_bio', true ); } )); }); This approach simplifies external integrations, making WordPress a powerful backend for web and mobile apps.
WP REST API – Custom Post Types And Fields
Set Up Your Custom Post Type for REST API
To include custom fields in your REST API responses, your custom post type must first be configured to work with the WordPress REST API. By default, custom post types are hidden from the REST API, meaning any attempt to access them results in 404 errors.
The key to enabling REST API integration lies in a specific parameter that determines whether your custom post type will be accessible through API endpoints. Without this setup, custom fields cannot be accessed. This is the essential first step in integrating your custom field data.
Enable REST API Support with show_in_rest
The show_in_rest parameter is what makes your custom post type available through the WordPress REST API. When you register a new custom post type, you need to include this parameter and set it to true in the arguments array.
"When registering a custom post type, if you want it to be available via the REST API you should set
'show_in_rest' => truein the arguments passed toregister_post_type." [3]
Here’s an example of how to register a custom post type with REST API support right from the start:
add_action( 'init', 'my_book_cpt' ); function my_book_cpt() { $args = array( 'public' => true, 'show_in_rest' => true, 'label' => 'Books' ); register_post_type( 'book', $args ); } This snippet registers a ‘book’ custom post type, making it accessible via the REST API under the wp/v2 namespace [3]. Once registered, you can access the ‘book’ posts at yoursite.com/wp-json/wp/v2/book.
To create a more user-friendly endpoint, you can use the rest_base parameter. This lets you customize the endpoint URL:
$args = array( 'public' => true, 'show_in_rest' => true, 'rest_base' => 'books', 'label' => 'Books' ); With this adjustment, the endpoint becomes yoursite.com/wp-json/wp/v2/books, replacing the default singular form.
Update Existing Custom Post Types
If you’re working with existing custom post types, you can enable REST API support using a filter. Many WordPress sites have custom post types created without REST API compatibility. Instead of recreating these post types, you can modify their settings with the register_post_type_args filter hook.
This method is particularly helpful when dealing with custom post types created by third-party plugins or themes. The filter lets you tweak the post type arguments before WordPress finalizes the registration.
add_filter( 'register_post_type_args', 'my_post_type_args', 10, 2 ); function my_post_type_args( $args, $post_type ) { if ( 'book' === $post_type ) { $args['show_in_rest'] = true; $args['rest_base'] = 'books'; $args['rest_controller_class'] = 'WP_REST_Posts_Controller'; } return $args; } This code targets the ‘book’ post type and adds REST API support without impacting other custom post types on your site [3]. After applying this filter, the modified post type becomes accessible via the /wp/v2/books endpoint, enabling full REST API functionality for existing content.
The rest_controller_class parameter specifies the controller that handles REST API requests. For most use cases, the default WP_REST_Posts_Controller works seamlessly for standard operations like creating, reading, updating, and deleting posts.
Without setting the show_in_rest parameter to true, your custom post type remains hidden from the REST API. As WordPress developer Scott Bolinger notes:
"Any custom post type that you want to be available to the WP-API needs to have the show_in_rest = true argument." [4]
With this setup, you’ve laid the groundwork for exposing your custom fields through the REST API. Once your custom post type is properly configured, you can proceed to include custom field data in your API responses.
Add Custom Fields to REST API
After setting up your custom post type for REST API access, the next step is sharing your custom field data via API endpoints. WordPress provides a few ways to do this, each suited to different levels of complexity and customization.
Two common methods include using WordPress’s register_rest_field function for precise control or relying on the Advanced Custom Fields (ACF) plugin for a simpler, more integrated approach. Both allow you to include custom field data in your API responses, but they differ in how much effort and customization they require. Use register_rest_field for detailed control, or ACF for easier implementation.
Using register_rest_field to Add Custom Fields
The register_rest_field function is a robust way to include custom fields in your REST API responses. By hooking into the rest_api_init action, you can ensure your custom fields are available specifically for API operations without affecting other WordPress functionality.
Here’s how it works: you define the object type, the field name for the API, and an array containing callback functions and schema details.
Below is an example of adding an event_date custom field to an events custom post type:
add_action( 'rest_api_init', function() { register_rest_field( 'events', 'event_date', array( 'get_callback' => function( $post_arr ) { $post_obj = get_field('event_date', $post_arr['id'] ); return $post_obj; }, 'update_callback' => function( $karma, $post_obj ) { update_field('event_date', $karma, $post_obj['id'] ); return true; }, 'schema' => array( 'event_date' => __( 'event_date' ), 'type' => 'text' ), )); }); In this example:
get_callbackretrieves the custom field value during a GET request, often using functions likeget_post_metaor ACF’sget_field.update_callbackhandles POST requests, letting you modify the field value using functions likeupdate_post_metaor ACF’supdate_field.- Schema helps define the field’s purpose and can assist with automated testing and validation.
Each custom field should be registered individually to allow for specific processing and validation.
For those looking for a more straightforward approach, ACF offers built-in REST API integration.
Leveraging Advanced Custom Fields (ACF)
ACF makes it easier to expose custom fields to the REST API, offering both interface-based settings and programmatic options. Since version 5.11, ACF supports REST API integration out of the box.
Enabling ACF Fields via the Interface
You can expose ACF fields through the WordPress admin interface:
- Go to your field group settings.
- Under the "Group Settings" tab, enable the "Show in REST API" option.
By default, ACF field groups are hidden from the REST API for security reasons. Once enabled, these custom fields will appear in the appropriate API endpoints for posts, users, or categories.
ACF Field Types and API Compatibility
ACF supports various field types, each with specific formats and behaviors in the REST API:
| Field Type | Expected Format | Notes |
|---|---|---|
| Text/Text Area | string, null | Standard text content |
| Number/Range | number, null | Accepts numeric strings (e.g., ‘123’) |
| string (email), null | Invalid formats return a 400 error | |
| Image/File | integer, null | Requires attachment ID |
| True/False | boolean, null | Accepts 0, 1, or equivalent strings |
| Date Picker | string, null | Must follow Y-m-d format |
| Gallery | number[], null | Array of attachment IDs |
| Repeater | array, null | Array of objects with subfield values |
Making API Requests with ACF
ACF supports GET, OPTIONS, and POST requests for custom fields, ensuring secure, JSON-encoded interactions. When updating fields via POST, include your data as a JSON-encoded acf object. Authentication is handled by WordPress’s core methods, ensuring only authorized users can modify field data.
Advanced Configuration Options
For custom post types created through ACF, REST API settings can be adjusted by navigating to ACF > Post Types and selecting the desired post type. Under the "Advanced Configuration" section, you’ll find a "REST API" tab where you can fine-tune how custom post types and their fields appear in API responses.
Additional customization options include:
acf_formatParameter: Adjusts how ACF fields are displayed in API responses.acf/rest/format_value_for_restFilter: Lets you modify field output for API requests.- Disabling ACF REST API: To turn off ACF’s REST API support entirely, use the
acf/settings/rest_api_enabledfilter and returnfalse.
These tools give you the flexibility to tailor ACF’s REST API integration to your needs.
sbb-itb-77ae9a4
Create Custom Endpoints for More Control
Default REST API endpoints might not always meet your needs. Custom endpoints give you the flexibility to define how data is structured, what information is returned, and how users interact with your application.
These endpoints are especially handy when you need to combine data, apply filters, or generate tailored responses. They also help improve performance by delivering only the specific data your application requires.
Register a Custom Endpoint Step by Step
To create a custom endpoint, use the register_rest_route function, which is hooked to the rest_api_init action.
Here’s the basic setup you’ll need:
- A namespace to avoid conflicts with other plugins.
- A route to define the URL path.
- An arguments array to specify the endpoint’s behavior.
Here’s an example of how to register a custom endpoint for fetching event data with custom fields:
add_action( 'rest_api_init', function() { register_rest_route( 'mysite/v1', '/events/(?P<id>\d+)', array( 'methods' => 'GET', 'callback' => 'get_custom_event_data', 'permission_callback' => '__return_true', 'args' => array( 'id' => array( 'validate_callback' => function( $param, $request, $key ) { return is_numeric( $param ); }, 'sanitize_callback' => 'absint', ), ), )); }); The namespace mysite/v1 ensures your endpoint doesn’t interfere with others. The route /events/(?P<id>\d+) uses a regular expression to capture the event ID from the URL, passing it as a parameter to your callback function.
Since WordPress 5.5, you must include a permission_callback for all custom endpoints. Using __return_true makes the endpoint public, but you can replace it with custom permission logic to restrict access based on user roles or other conditions.
The args array defines how parameters are handled. For instance, in the example above, the id parameter is validated to ensure it’s numeric and sanitized with absint() to convert it to a positive integer.
Fetch and Return Custom Field Data
The callback function is where the magic happens. It processes the request, retrieves the necessary data, and returns a structured response. Here’s a complete example:
function get_custom_event_data( $request ) { $event_id = $request->get_param( 'id' ); // Verify the post exists and has the correct type $post = get_post( $event_id ); if ( ! $post || $post->post_type !== 'events' ) { return new WP_Error( 'event_not_found', 'Event not found', array( 'status' => 404 ) ); } // Retrieve custom field data $event_data = array( 'id' => $event_id, 'title' => $post->post_title, 'content' => $post->post_content, 'event_date' => get_post_meta( $event_id, 'event_date', true ), 'event_location' => get_post_meta( $event_id, 'event_location', true ), 'ticket_price' => get_post_meta( $event_id, 'ticket_price', true ), 'organizer_email' => get_post_meta( $event_id, 'organizer_email', true ), 'featured_image' => get_the_post_thumbnail_url( $event_id, 'large' ), ); // Remove empty fields to reduce response size $event_data = array_filter( $event_data, function( $value ) { return ! empty( $value ); }); return rest_ensure_response( $event_data ); } This function ensures the post exists and is the correct type, retrieves custom field data, filters out empty values, and formats the response. The rest_ensure_response() function converts the data into a WP_REST_Response object.
For more advanced use cases, you can create endpoints that handle multiple events or allow filtering by specific criteria:
register_rest_route( 'mysite/v1', '/events', array( 'methods' => 'GET', 'callback' => 'get_filtered_events', 'permission_callback' => '__return_true', 'args' => array( 'location' => array( 'sanitize_callback' => 'sanitize_text_field', ), 'date_from' => array( 'sanitize_callback' => 'sanitize_text_field', ), 'limit' => array( 'default' => 10, 'sanitize_callback' => 'absint', ), ), )); This example adds parameters like location, date_from, and limit to filter events by location, date, or the number of results returned. Each parameter includes a sanitization callback to ensure data security.
With these endpoints, you can access your data through URLs like yoursite.com/wp-json/mysite/v1/events/123 or yoursite.com/wp-json/mysite/v1/events?location=downtown&limit=5. This level of customization gives you full control over how your data is accessed and presented through the REST API.
Next, we’ll dive into best practices for securing and optimizing your REST API responses.
Best Practices for Custom Fields in REST API
Following these practices will help ensure your REST API implementation remains secure, efficient, and easy to maintain when working with custom fields.
Add Security with Permission Callbacks
Security is a cornerstone of any REST API. Every endpoint should include proper checks to safeguard sensitive data. In WordPress, this is achieved using a permission_callback. This function determines whether the current user has the necessary permissions to perform a specific action. For public endpoints, you can use __return_true, but for restricted endpoints, rely on current_user_can() to enforce role-based capabilities.
"The permissions callback is run after remote authentication, which sets the current user. This means you can use
current_user_canto check if the user that has been authenticated has the appropriate capability for the action, or any other check based on current user ID. Where possible, you should always usecurrent_user_can; instead of checking if the user is logged in (authentication), check whether they can perform the action (authorization)." [5]
Here’s an example of how to implement permission checks for different user roles:
function secure_event_permission_callback( $request ) { // Allow read access to everyone if ( $request->get_method() === 'GET' ) { return true; } // Require edit_posts capability for modifications if ( ! current_user_can( 'edit_posts' ) ) { return new WP_Error( 'rest_forbidden', 'You do not have permission to modify events.', array( 'status' => 403 ) ); } return true; } You can also create role-specific restrictions. For example, you might limit Editors to read-only access while allowing Authors to manage their own posts:
function restrict_editor_api_access() { $editor_role = get_role('editor'); $editor_role->remove_cap('edit_posts'); $editor_role->remove_cap('edit_others_posts'); $editor_role->remove_cap('edit_published_posts'); $editor_role->remove_cap('delete_posts'); $editor_role->remove_cap('delete_published_posts'); } add_action('init', 'restrict_editor_api_access'); For more tailored control, you can define custom roles with specific API permissions:
function create_custom_role() { add_role('content_manager', 'Content Manager', array( 'read' => true, 'edit_posts' => false, 'delete_posts' => false, 'publish_posts' => false, 'upload_files' => true, // Allow uploading media )); } add_action('init', 'create_custom_role'); Once your security measures are in place, the next step is to optimize your API responses for speed and efficiency.
Optimize API Responses
After securing your endpoints, focus on delivering faster and more efficient responses. Large payloads can slow down applications and increase server load, so it’s important to tailor your API responses.
Limit the data returned by specifying only the fields you need:
"Reduce payload size by requesting only what you need: /wp-json/wp/v2/posts?_fields=id,title,excerpt" [1]
For endpoints that return multiple items, implement pagination using the per_page and page parameters. This helps break large datasets into smaller, more manageable chunks:
'args' => array( 'per_page' => array( 'default' => 10, 'sanitize_callback' => 'absint', 'validate_callback' => function( $param ) { return $param >= 1 && $param <= 100; }, ), 'page' => array( 'default' => 1, 'sanitize_callback' => 'absint', ), ), For frequently accessed endpoints, consider server-side caching to reduce response times. WordPress transients are a great tool for this:
function get_cached_events() { $cache_key = 'custom_events_api_response'; $cached_data = get_transient( $cache_key ); if ( false === $cached_data ) { // Fetch fresh data $cached_data = fetch_events_data(); set_transient( $cache_key, $cached_data, HOUR_IN_SECONDS ); } return $cached_data; } By caching repeated requests, you can significantly improve performance and reduce server strain.
Keep Consistent Naming and Documentation
Clear and consistent naming conventions are essential for effective API collaboration. They make your API predictable and easier to use, which is especially important for team integration.
- Use plural nouns for resource endpoints to align with REST principles. For example, use
/eventsinstead of/eventand/locationsinstead of/location. - Stick to lowercase words separated by hyphens for readability. For instance, prefer
event-locationsovereventLocationsorEvent_Locations. - Avoid file extensions in endpoint URIs. Instead of
/events.json, use/eventsand specify the data format through theContent-Typeheader.
Parameter names should be descriptive and self-explanatory. Instead of generic terms like param1 or data, use meaningful names like event_date, location_name, or ticket_price.
To ensure consistency across the team, document your naming conventions in a style guide. This guide should cover:
- Resource naming patterns (e.g., plural nouns, lowercase, hyphen-separated)
- Parameter naming conventions (e.g., descriptive and aligned with database fields)
- Response field naming (e.g., camelCase or snake_case)
- Error message formatting (e.g., consistent structure and language)
Adopting clear naming and documentation practices makes your API easier to maintain and scale as new endpoints are added, while also improving the experience for developers using it.
Conclusion: Get More from WordPress REST API
This guide has walked you through the process of extending the functionality of the WordPress REST API. Let’s recap the essentials. Adding custom fields to your WordPress REST API allows for seamless integration with external services and applications. The process boils down to three main steps: enabling REST API support for your custom post types using show_in_rest, registering custom fields with register_rest_field, and ensuring security with permission callbacks.
If you’re using Advanced Custom Fields (ACF), version 5.11 introduced built-in REST API support, which can be activated via field group settings [2][6]. For more advanced needs, you can create custom endpoints to handle complex data structures. Just make sure to stick to WordPress naming conventions, such as the vendor/v1 pattern, to avoid plugin conflicts [5].
Testing and authentication are critical to ensuring everything works smoothly. The WordPress REST API is a powerful tool that can serve as the backbone for headless WordPress setups, mobile app backends, and intricate web applications. By mastering these techniques, you can fully leverage WordPress as both a content management system and a platform for application development.
For those eager to sharpen their WordPress skills, WP Winners is a fantastic resource. It offers in-depth tutorials, guides, and tips for developers of all levels. From performance tweaks to security improvements and customization options, their content is packed with practical advice for building strong REST API implementations.
Whether you’re upgrading a simple blog or crafting a complex application, the WordPress REST API provides the flexibility to deliver outstanding user experiences. Start by integrating custom fields and scale up to advanced endpoints as your project demands. Check out WP Winners for more actionable WordPress tips and strategies.
FAQs
How do I make my custom post types accessible in the WordPress REST API?
To make your custom post types available in the WordPress REST API, you need to include the 'show_in_rest' => true argument when registering the post type using the register_post_type function. This allows the post type to be part of the API under the wp/v2 namespace. Here’s a quick example:
add_action( 'init', 'register_my_custom_post_type' ); function register_my_custom_post_type() { $args = array( 'public' => true, 'show_in_rest' => true, 'label' => 'My Custom Post' ); register_post_type( 'my_custom_post', $args ); } Keep in mind that only published posts will show up in the REST API. If your custom post type has restricted access, you might need to create a custom REST controller to properly handle permissions and access rules.
What should I consider for security when adding custom fields to the WordPress REST API?
When working with the WordPress REST API, protecting your site’s security should be a top priority, especially when adding custom fields. Be cautious about exposing private or sensitive data through the API. Tools like Advanced Custom Fields (ACF), for instance, keep data private by default unless you intentionally configure it to be accessible.
To strengthen security, make sure to include authentication and user role checks. These measures help ensure only authorized users can view or modify specific data. Additionally, disabling unused REST API endpoints can minimize vulnerabilities and reduce the risk of attacks. Managing access permissions and carefully controlling data visibility are crucial steps to keep your integration secure.
Can I use the Advanced Custom Fields (ACF) plugin to easily add custom fields to REST API endpoints?
The Advanced Custom Fields (ACF) plugin makes it easy to integrate custom fields into your REST API endpoints. Starting with version 5.11, ACF includes built-in support for the WordPress REST API, enabling smooth access and management of custom field data.
To use this feature, simply tweak the REST API visibility settings for specific field groups within the ACF settings. This functionality gives you greater control over customizing and extending your WordPress REST API.