Some time ago, WordPress introduced an Application Programmer Interface (API) to streamline our interactions with WordPress servers. Being a curious and passionate web developer, I embarked on a journey to explore the intricacies of this API, its power and versatility. I invite you to join me as we delve into the workings of the WordPress API.
To API or Not to API
In the realm of programming, APIs are gateways that allow for data manipulation on servers through Hyper Text Transmission Protocols (HTTP). There are four primary HTTP methods, often referred to as HTTP verbs:
- GET retrieves information from the server.
- POST creates a new file on the server.
- PUT updates an existing file on the server.
- DELETE removes a file from the server.
Understanding these methods is vital, but it is equally important to know how servers respond to our interactions. Here are some of the crucial status codes:
- 200 – OK: Successful request.
- 201 – Created: File successfully created on the server.
- 400 – Bad Request: The server couldn’t complete the request.
- 401 – Unauthorized: User authentication failed.
- 403 – Forbidden: The user is authenticated but not permitted to perform the requested action.
Choosing Your Routes
Understanding routes and endpoints is another key aspect of working with APIs.
- Routes point to specific resources.
- Endpoints are functions that trigger actions on resources, which can be any of the aforementioned HTTP methods.
Consider this: A route to your WordPress posts could be ‘/wp-json/wp/posts’, and the endpoints might be ‘GET /wp-json/wp/posts’ and ‘POST /wp-json/wp/posts’. The first endpoint triggers a GET method, retrieving posts from WordPress, while the second creates a new post on the server after validating and authenticating user permissions.
As an example, for a specific post with ID = 10 on WordPress, the route could be ‘/wp-json/wp/posts/10’, while the endpoints would be:
- GET /wp-json/wp/posts/10 – Retrieve the specific post.
- PUT /wp-json/wp/posts/10 – Update the specific post.
- DELETE /wp-json/wp/posts/10 – Delete the specific post.
Notably, many APIs, including WordPress, treat POST and PUT as identical, meaning substituting POST for PUT in the previous example would still result in the updating of the specific post. These methods, routes, and endpoints are applicable to any resource, including pages, posts, comments, images, etc.
Get Jumping with JSON
The WordPress REST API extensively utilizes JSON (JavaScript Object Notation) for data interchange. JSON represents data in a key-value format, with the key denoting the property name. For instance, a post object in JSON format includes these keys:
- id
- type
- slug
- url
- title
- title_plain
- content
- excerpt
- date
- modified
- categories
- tags
- author
- comments
- attachments
- comment_count
- comment_status
- thumbnail
- custom_fields
- taxonomy_(taxonomy)
When parsing JSON, remember that all string elements are enclosed in double-quotes. This is a mandatory format for JSON, even though JavaScript doesn’t strictly enforce it.
Access Your WordPress API
Every WordPress installation has its own WordPress API, which is accessible at: domainName.com/wp-json/. Making a GET request to this URL through a tool like Postman returns the website information in JSON format. The returned data include:
- Website name
- Tagline for the website
- Web address
- Location of the website
- All namespaces registered by the WP REST API, plugins, and themes
- All authentication methods supported by the API
- All supported routes for the WP REST API
Each route is listed as an individual object with properties including namespace, HTTP methods, endpoints, and arguments. The “_links” array contains associated resources based on Hypertext Application Language (HAL).
Down the Rabbit Hole
To delve further into a specific route and understand its methods and supported arguments, we send an OPTIONS request to that route. This returns an object containing the namespace, supported HTTP methods, and endpoints.
Sending an OPTIONS request to the posts/ route returns two supported methods (GET and POST), along with multiple arguments, including (for GET): context, page, per_page, search, after, author, author_exclude, before, exclude, include, offset, order, orderby, slug, status, categories, categories_exclude, tags, tags_exclude, sticky.
For POST, the supported arguments include date, date_gmt, slug, status, password, title, content, author, excerpt, featured_media, comment_status, ping_status, format, meta, sticky, template, categories, tags.
Alongside these, we also receive a schema for the particular resource, a documentation of all the properties supported by the resource.
So, to explore all supported routes for an API, send a GET request to the index route. However, if you need to dive deeper into individual routes, send an OPTIONS request to that route.
Exploring the WordPress API is a fascinating journey, unveiling its capacity to provide a smooth, structured interaction with WordPress servers. Regardless of your role, whether a developer or a WordPress site manager, a solid understanding of the WordPress API will greatly enhance your proficiency and efficiency. Happy coding!