REST API & GraphQL

Overview

This project leverages both the WordPress REST API and WPGraphQL to expose content to decoupled frontends and external services. Depending on your performance requirements and data structures, you can choose between the traditional RESTful approach or the flexible Graph-based approach.

REST API

The REST API provides a collection of JSON endpoints for interacting with WordPress data. It is best used for simple data fetching or when integration with standard HTTP-caching layers is required.

Base Endpoint

All REST requests should be directed to the following base URL: GET https://your-domain.com/wp-json/wp/v2/

Common Endpoints

Usage Example

To fetch the 5 most recent posts with embedded media and author details:

GET /wp-json/wp/v2/posts?per_page=5&_embed

Response (Type: JSON):

[
  {
    "id": 101,
    "date": "2023-10-27T10:00:00",
    "title": { "rendered": "Sample Post Title" },
    "content": { "rendered": "<p>Content here...</p>" },
    "link": "https://example.com/sample-post",
    "_embedded": {
      "author": [...],
      "wp:featuredmedia": [...]
    }
  }
]

Filtering & Pagination

per_page: Number of items to return (1-100).
page: Current page of results.
orderby: Sort results by date, id, title, or slug.

WPGraphQL

For complex data structures or to reduce "over-fetching," use the GraphQL endpoint. This allows you to request exactly the fields you need in a single request.

Endpoint

POST https://your-domain.com/graphql

Querying Data

WPGraphQL uses a typed schema. You can explore the schema using GraphiQL in the WordPress admin dashboard.

Example: Fetching Post Titles and Excerpts

query GetPosts {
  posts(first: 10) {
    nodes {
      id
      title
      excerpt
      date
      featuredImage {
        node {
          sourceUrl
          altText
        }
      }
    }
  }
}

Variables Example:

{
  "first": 5,
  "after": "cursor-id"
}

Response Format

The response is always returned as a JSON object with a data key.

{
  "data": {
    "posts": {
      "nodes": [
        {
          "id": "cG9zdDox",
          "title": "Hello World",
          "excerpt": "Welcome to WordPress...",
          "date": "2023-10-27T10:00:00",
          "featuredImage": null
        }
      ]
    }
  }
}

Authentication

Public data is available via GET requests without authentication. However, to access drafts, private posts, or perform write operations (POST/PUT/DELETE), you must authenticate.

Application Passwords

The recommended method for external applications is Application Passwords (available in WordPress User Profiles).

Header Implementation:

# Encode 'username:application-password' in Base64
Authorization: Basic <base64-encoded-string>

Custom Fields and ACF

If you are using Advanced Custom Fields (ACF), these are exposed via both interfaces:

REST API: Fields appear under the acf key in the response object (requires the "Show in REST API" toggle to be enabled in ACF settings).
WPGraphQL: Use the acfFieldGroupName property within your query to retrieve specific field groups.

# WPGraphQL ACF Example
{
  posts {
    nodes {
      myCustomFieldGroup {
        fieldOne
        fieldTwo
      }
    }
  }
}