Extending Core WordPress REST API Routes With Pods
This document details features that were added in Pods 2.6. In addition they require the WordPress REST API plugin version 2-beta9 or later and WordPress 4.3.1 or later. UPDATE: The WordPress REST API plugin is now included in WP Core as of WP 4.6. The separate plugin is no longer necessary.
Pods can be used to extend default WordPress REST API endpoints for any post types and taxonomies as well as the user routes. This functionality, which is managed from the Pods editor can be used to do the following:
- Add endpoints a custom post type or custom taxonomy, which by default is not enabled.
- Read and or modify Pods fields in requests to the endpoints for a post type, taxonomy or users.
These capabilities are detailed below.
The WordPress REST API is a new feature being added to WordPress 4.4 and 4.5. It can also be added using a plugin. WordPress 4.4 will add infrastructure for creating RESTful APIs using WordPress. Version 4.5 will use that infrastructure to create “default routes” for WordPress posts (of any type,) comments, taxonomies and users. All of this functionality is available when using the WordPress REST API plugin and WordPress 4.3 or later.
Pods 2.6 adds the ability to extend the default routes. Therefore, until the default routes are included in WordPress, the Pods REST API functionality requires the plugin be active.
Routes added by Pods use the same functionality as the default routes for built-in post types, and taxonomies. This means that using your Pods routes is functionally identical to using any other route. If you know how the defaults work, then you know how they work in Pods. This document covers how to enable that support and further useful information. If you would like to learn more about the WordPress REST API, I wrote a free eBook on the subject, which I recommend 🙂
Custom Content Types, The REST API, Pods & You
By default custom post types, and custom taxonomies do not have routes. That means that if you have a custom post type called “jim” you will not automatically get an endpoint at “/wp-json/wp/v2/jim” and you can not query posts in the “jim” post type at “wp-json/wp/v2/posts”. But custom post types can declare support for the REST API. The same is true for custom taxonomies.
Pods respects the core default, and does not, by default, add REST API support when creating custom post types and taxonomies. This new functionality is optional, and must be manually enabled.
Pods provides, from the UI, the ability to add these routes. Once enabled for the post type “jim” you will be able to create, read, update and delete posts in the “jim” post type, using routes that function identically to the default “post” post type route. The routes for the “jim” post type would available at “wp-json/wp/v2/jim”
Custom taxonomies added by Pods work the same way. Once support is enabled, a set of routes that function like the routes for categories and tags.
Custom Fields, The REST API, Pods & You
The WordPress REST API provides a separate set of endpoints for custom fields. For post type Pods using default meta storage, or an extended users Pod using default meta storage these routes are available to you as well. If you are using table storage they will not be useful.
The WordPress REST API provides functionality to add custom fields of any type to default routes. In this context “custom fields” refers to any data that is added to a response, not post / user/ term meta fields, but is an excellent example of a type of data you would use.
Pods allows you to make your Pods fields available for reading and/ or writing in the route for your Pods custom content type. This functionality is disabled by default. It can be enabled for all fields, or per field.
Extending WordPress Default Objects
The WordPress REST API has a set of routes for user data, as well as default post types and taxonomies, which are enabled by default. Pods can be used to extend these objects.
When you extend a default post type, taxonomy, or the users object, you have the same options for managing Pods fields via those routes as with custom content types.
How It Works
The following instructions are for enabling the various types of support using the Pods editor. Working with this data via the REST API is not detailed here. Please refer to the REST API documentation. To learn more about working with posts see chapters 1 and 3 of my book, for taxonomies see chapter 6 and for users see chapter 7.
If you have the plugin enabled, you will see a “REST API” tab in the Pods editor for post type, taxonomy and user fields. Click the “enable” option to enable REST API support for this content type.
Once support is enabled, new options are visible in this tab. The first new option”REST Base” defines the main route for the post type. By default, it is the name of your Pod. If you add REST support to a custom post type Pod called “scott” the routes will exist at “wp-json/wp/v2/scott” if you wish to change that to “wp-json/wp/v2/scottkclark” you would change the “REST Base” setting to “scottkclark”.
Enabling REST support gives you the routes, detailed above, for these content types. It does not provide for editing or reading Pods field data via these endpoints. This can be done in one of two ways:
- Globally – In the REST API tab are options for showing all fields or allowing all fields to be updated via this route.
- Per field — Once REST Support is enabled, each field has read/ write via REST options. The global options will override the individual field options.
Relationship fields have additional settings. All relationship fields have settings for “Response Type” and “Depth”.
The “Response Type” setting has three options:
- Full – This returns all information from related fields.
- ID Only – This returns the ID of the related object(s) only.
- Name Only — This returns the name (post title, term name, etc) of the related object(s) only
The “depth” setting only has any effect when the response type is set to “full.” This setting controls how far Pods will traverse related field data. If the field is related to a post type, that has a relationship to another Pod, which is related to another Pod, that can result in three levels of traversal. That’s a lot of data, and a lot of queries. If you do not need all of that data, use a lower setting for depth.
Pods Advanced Content Types, Custom Queries & More
At this time Pods does not provide routes for advanced content types. It also does not provide the ability to use the Pods class for queries via the REST API. These are intentional design decisions, made for the following reasons:
- Pods Advanced Content Types can not use the controllers provided by the core REST API, since those routes use standard WordPress APIs such as WP_Query, WP_User_Query, etc.
- Creating an abstract method for running Pods queries that handles all use cases and is secure is impossible.
- Every Pods site has its own needs in terms of queries — mimicking the capabilities of the Pods class via an HTTP request would make all types of queries possible and probably not make the queries you need simple or RESTful.
- The WordPress REST API provides excellent infrastructure for making your own routes, or modify existing routes. I have provided an overview of the various options to do so, with extensive links on my site. Pete Nelson of 10up has an excellent presentation, with great example code on extending the REST API.