Practical Guide to REST API Resource Modeling

Key points: 

• Designing effective REST resources means defining independent, logically grouped data chunks that clients can address directly, avoiding performance and complexity pitfalls.
• Use the independence test, proper URI patterns, and HTTP methods to ensure clear boundaries, minimize client-side work, and maintain scalable, intuitive APIs.
• Advanced Custom Fields (ACF®)’s Show in REST API feature helps model and expose resources correctly in WordPress, combining visual field grouping with secure, REST-compliant data structures.

REST resources are just pieces of information that clients need to address directly. It sounds simple enough, yet a lot of developers get resource boundaries wrong, creating APIs that force frontend teams into callback hell and database queries that would make a DBA weep.

The core question isn’t whether your API follows REST principles perfectly. It’s simpler: “Am I splitting data into the right addressable chunks?” Get this wrong, and you’ll watch your mobile app make several separate requests just to render a user profile. Get it right, and your API is intuitive.

Developers waste countless hours debating REST theory when they need practical validation of their design decisions. Should user preferences be a separate resource or embedded in the user object? Does pagination belong in query parameters or response headers? These are engineering decisions with measurable performance impacts.

The Advanced Custom Fields (ACF®) plugin team understands this, which is why the Show in REST API toggle exists. That simple checkbox embodies proper resource thinking: make data addressable when clients need direct access, embed it when they don’t.

Let’s get you into the same mindset so you can start building REST API resources that are a real treat for the dev teams consuming them.

Understanding what makes a good REST API resource

In WordPress, posts, users, and custom post types each map to distinct resources because they represent fundamentally different data that clients manage independently. You can create a post without touching user data, update a user without affecting their posts, and delete custom entities without cascading changes.

Poor resource design forces clients into messy workarounds.

When user profiles, preferences, and activity feeds get mashed into a single resource, frontend developers end up making unnecessary requests or dealing with bloated responses. Even worse, something as simple as updating a user’s email suddenly requires validating their entire preference structure.

Good boundaries pass the independence test: changing one resource shouldn’t require updating others. This principle drives everything from naming patterns to HTTP method choices.

It would, for instance, pull you towards PATCH, which updates specific fields without requiring the full object that PUT demands.

When resources can evolve separately, your API becomes resilient to change.

Structuring your resources with the independence test

The independence test helps determine if you’ve properly split your API resources: can you create, update, or delete one resource without affecting another? If not, you may have over-engineered your resource boundaries.

The test is straightforward: ask yourself, “Can this data exist on its own?”

It fails if modifying one resource consistently requires changes to others. For instance, if updating a blog post forces a recalculation and storage of category statistics in a separate resource, those statistics should be part of the category resource, not kept independently. This kind of dependency shows that the resources aren’t truly independent.

A passing test could look like this: user preferences are meaningless without a user account, so they should be part of the user resource at /users/123 rather than a separate /users/123/preferences endpoint. Similarly, shopping cart items, which lose context without the parent cart, should be nested within the cart resource structure instead of being a standalone /cart-items/456 resource.

This approach lets you consolidate interdependent, overly granular resources into logical units that reflect how your application uses the data. This results in fewer endpoints to maintain, reduced HTTP requests for clients, and a simpler approach to managing data relationships.

Choosing the right URI design and HTTP method

When designing your API, you need to follow some key best practices for URI structure and HTTP method usage:

• Use plural for collections, singular for specific resources to keep the structure consistent and make it clear when referring to groups of resources versus individual ones, such as /posts for all posts and /posts/123 for a specific post.
• Map HTTP verbs to actions, i.e., GET retrieves, POST creates, PUT/PATCH updates, and DELETE removes. This aligns with the natural behavior of these methods and simplifies interactions.
• Understand when to use PUT vs PATCH, i.e., PUT to replace an entire resource, and PATCH to modify specific fields. For example, PUT would replace the full post, while PATCH could update only the title or content of the post.
• Avoid verbs in URLs since the HTTP method already expresses the action. So instead of using /getPosts, for example, simply use /posts, where GET indicates the retrieval action.
• Use nested URIs to indicate ownership relationships. For example, /posts/123/comments clearly shows that comments belong to the post with ID 123.
• Use query parameters for filtering collections. For example, /posts?status=published&author=5 allows clients to filter posts by status and author without needing additional endpoints.

Handling collections and performance

Here are some key strategies to ensure your API performs well while handling large datasets:

• Collections should return arrays of resources with a consistent structure across all endpoints. This ensures uniformity and simplifies how clients interact with your API, making it easier to manage large datasets.
• Use pagination parameters like ?page=2&per_page=10 to prevent massive response payloads. Pagination helps break down large datasets into manageable chunks, improving load times and reducing memory consumption.
• Implement field selection with ?_fields=id,title,date to reduce bandwidth and improve mobile performance. Allowing clients to request only the fields they need lets you minimize unnecessary data transfer and enhance overall performance.
• Cache collection responses aggressively, as they change less frequently than individual resources. This improves response times and reduces server load by avoiding repeated processing of the same data.
• Embed related data sparingly, as the independence test applies to what gets included automatically. Only include related resources when necessary, ensuring that your API remains efficient and avoids excessive coupling between resources.

Production-ready REST resource modeling with ACF

ACF extends existing WordPress REST API resources rather than creating new ones. The Show in REST API toggle injects custom field data directly into standard endpoints, maintaining REST conventions while adding domain-specific attributes.

Here’s the toggle as you’d see it when configuring a custom field group:

ACF transforms abstract resource modeling into visual WordPress admin interfaces. Instead of coding field definitions, developers configure field groups that map to resource boundaries. A product resource might include price, specifications, and inventory fields – all appearing as additional properties in the standard product endpoint response.

This approach preserves RESTful design by keeping related data unified within single resources rather than fragmenting it across multiple endpoints. Field group organization directly reflects proper resource modeling – cohesive attributes grouped together mirror how resources should be structured.

How to fetch ACF data via the REST API

The real test of any API resource is pulling data from outside. ACF’s REST API integration shines here – your custom fields become accessible endpoints that external applications can consume just like any other REST resource. Mobile apps, React frontends, and third-party services can all tap into ACF-powered endpoints to receive your custom content structure as neat JSON.

We’ll start with a custom post type for cars, which we’ll choose to show in the REST API. Here are the general field settings:

And here are the REST API settings, available under Advanced > REST API:

Now we can create some cars from the dashboard via Cars > Add New Car, then make an API request via https://yourwebsite.com/wp-json/wp/v2/car/ and see the data it returns:

💡 You can fetch a specific custom post by adding its ID to the end of the URL.

We can take this a step further by adding custom fields to the custom post type. Here, we’ll create custom fields for car details – year introduced and vehicle type – and connect them to the custom post type under the location rules:

Then make the data accessible via the REST API via Settings > Group Settings:

Finally, update your cars post(s) to fill in the custom field boxes.

Now, we can make the same API call from earlier and we should see the custom field data in the new acf section of the response:

How ACF handles REST API security and data exposure

A solid API security strategy protects sensitive information while still providing the necessary data to authorized users. ACF takes several steps to ensure that only the right data is exposed through the API:

• Field groups with Show in REST API enabled expose only those specific fields, not the entire database. This ensures that only the necessary fields are available, reducing the risk of unintended data exposure.
• ACF respects WordPress permissions, meaning users will only see fields for resources they already have access to. This ensures that data visibility aligns with the user’s roles and permissions in WordPress.
• You can use the _fields parameter to request specific ACF fields and avoid accidentally exposing sensitive data. This gives you granular control over what data is returned.
• Meta fields appear under a dedicated namespace in API responses, which helps maintain clear data boundaries. This separation makes it easier to differentiate between core WordPress data and custom fields.
• Field visibility in the REST API follows the same rules as the admin interface, ensuring that no additional security holes are created.

Build professional APIs with ACF’s smart resource patterns

When building REST APIs, developers often struggle with defining the correct resource boundaries, which can lead to performance issues and complex, hard-to-manage systems.

The key to success lies not in strictly adhering to REST principles, but in ensuring that data is split into the right addressable chunks. If you mismanage this, users might end up making unnecessary API calls, or worse, your API could force frontend developers into tricky workarounds.

Applying the independence test to your API resources ensures that data changes are isolated to the relevant resource, preventing unwanted side effects.

With ACF, you have practical tools at your disposal to design API resources that are intuitive, efficient, and scalable. Its visual field groups and REST API toggles help you easily define which data is exposed and how it’s structured, avoiding guesswork.

With pagination, field selection, and efficient caching, your API can scale effectively while maintaining fast response times. Coupled with ACF’s respect for WordPress permissions and security measures, this approach makes building professional REST APIs straightforward and hassle-free.

Check out ACF today and start building smarter, faster APIs that developers will love.