CMM-1177/CMM-1178 create the top post and referrers endpoints by adalpari · Pull Request #1119 · Automattic/wordpress-rs

adalpari · 2026-01-26T11:50:30Z

Summary

Adds new WordPress.com REST API endpoints for fetching site statistics:
- Top Posts (/rest/v1.1/sites/<site_id>/stats/top-posts) - Returns most viewed posts/pages
- Referrers (/rest/v1.1/sites/<site_id>/stats/referrers) - Returns traffic referrer sources

Implementation Details

New Files

Top Posts Endpoint:

wp_api/src/wp_com/stats_top_posts.rs - Types, parameters, response structures, and helper functions
wp_api/src/wp_com/endpoint/stats_top_posts_endpoint.rs - Endpoint definition
wp_api/tests/wpcom/stats_top_posts/top-posts-01.json - Test data fixture

Referrers Endpoint:

wp_api/src/wp_com/stats_referrers.rs - Types, parameters, response structures, and helper functions
wp_api/src/wp_com/endpoint/stats_referrers_endpoint.rs - Endpoint definition
wp_api/tests/wpcom/stats_referrers/referrers-01.json - Test data fixture

Modified Files

wp_api/src/wp_com/mod.rs - Module registration
wp_api/src/wp_com/endpoint.rs - Endpoint module registration
wp_api/src/wp_com/client.rs - Request builder and executor integration

API Parameters

Top Posts:

Parameter	Type	Description
`period`	`StatsTopPostsPeriod`	Time period grouping (day, week, month, year)
`start_date`	`String`	Start date in YYYY-MM-DD format
`date`	`String`	Query date in YYYY-MM-DD format
`max`	`u32`	Maximum number of top posts to return

Referrers:

Parameter	Type	Description
`period`	`StatsReferrersPeriod`	Time period grouping (day, week, month, year)
`date`	`String`	Query date in YYYY-MM-DD format
`start_date`	`String`	Start date in YYYY-MM-DD format
`max`	`u32`	Maximum number of referrers to return

Helper Functions

Top Posts:

get_stats_top_posts_all_post_views() - Returns all post views from all days
get_stats_top_posts_for_date() - Returns post views for a specific date
get_stats_top_posts_total_views() - Returns total views across all days

Referrers:

get_stats_referrers_all_groups() - Returns all referrer groups from all days
get_stats_referrers_for_date() - Returns referrer data for a specific date
get_stats_referrers_total_views() - Returns total views across all days

Notable Implementation Details

The referrers endpoint has a polymorphic results field that can be either:

A simple views object: {"views": 12}
A detailed referrer array (e.g., for Search Engines): [{"name": "Google Search", ...}]

This is handled using #[serde(untagged)] enum (StatsReferrersResults).

jkmassel

Good start – this properly parsed both https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/stats/referrers and https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/stats/top-posts (with summarize=1).

Left some inline suggestions.

wp_api/src/wp_com/stats_referrers.rs

jkmassel · 2026-01-26T22:12:28Z

wp_api/src/wp_com/stats_referrers.rs

+
+/// Parameters for the stats referrers endpoint.
+#[derive(Debug, Default, PartialEq, Eq, uniffi::Record)]
+pub struct StatsReferrersParams {


This needs to take a locale param – that's used to translate the response's strings (for example "Search Engines").

It should probably be an enum that matches WP.com locales - @crazytonyli wdyt about using WPComLanguage from #1011?

Good catch! Added here

wdyt about using WPComLanguage?

That makes sense to me. I presume the local argument in this request is treated as the same as WPComLanguage.slug in the backend.

wp_api/src/wp_com/stats_top_posts.rs

wp_api/src/wp_com/stats_referrers.rs

jkmassel · 2026-01-29T16:42:49Z

wp_api/src/wp_com/stats_referrers.rs

+    #[rstest]
+    #[case("tests/wpcom/stats_referrers/referrers-01.json")]
+    #[case("tests/wpcom/stats_referrers/referrers-03-follow-data-false.json")]
+    #[case("tests/wpcom/stats_referrers/referrers-04-real-response.json")]


This is a good parameterized test, but should include all of the test cases you've defined. Even if they're used for a more specific test, running every valid json test case you have through the generic deserialization test is more likely to catch issues.

Said another way – you have the data anyway, might as well use it :)

You are right. The problem is that because of the endpoint specifications, some JSON files are different.
For instance, referrers-02-days.json has no period field. So, it cannot be included in this general test.
However, there's a specific test for it.

Note: I've added referrers-05-with-nulls.json, though, and an extra check.

Done here: 2c589f4

For instance, referrers-02-days.json has no period field

This seems odd – https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/stats/referrers?summarize=1&period=day has a period field, but https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/stats/referrers?period=day does not. Should we be using the former?

jkmassel · 2026-01-29T23:00:01Z

To help land this quicker, I've:

Rebased this PR atop trunk now that Add language endpoint and database #1011 and Rework WP.com e2e tests to remove custom test harness and run in CI #1126 have landed.
Opened Cmm 1177 suggestions #1133 with an implementation of the WP.com e2e tests covering these new endpoints.

Still to do – if we really need both summarize=1 and summarize=0, we should support both. The fact that we can't run the parser tests over all of our JSON files means something's not quite right – we should be able to (if they have different expectations – like one should always have Some summary, for instance, that can be baked into the test definition and doesn't need to be part of the test function body.

adalpari · 2026-01-30T08:49:53Z

To help land this quicker, I've:

Rebased this PR atop trunk now that Add language endpoint and database #1011 and Rework WP.com e2e tests to remove custom test harness and run in CI #1126 have landed.

Opened Cmm 1177 suggestions #1133 with an implementation of the WP.com e2e tests covering these new endpoints.

Thank you!!

Still to do – if we really need both summarize=1 and summarize=0, we should support both. The fact that we can't run the parser tests over all of our JSON files means something's not quite right – we should be able to (if they have different expectations – like one should always have Some summary, for instance, that can be baked into the test definition and doesn't need to be part of the test function body.

We are already supporting both outputs. In tests, we can parse both as well (but in different tests).
However, given that each test checks different output fields, they cannot be mixed. One test checks period and summary.groups, while the other one checks summary.is_none() and days.is_some().

I've tried to follow your suggestion about "baking it into the test definition". So, let me know if you think this is a good approach: fde295e

* Add WP.com e2e tests fx * Use `WPComLanguage` for locale * Explicitly specify `summarize` for for all requests

…om:Automattic/wordpress-rs into task/CMM-1177-create-the-top-post-endpoint

adalpari · 2026-02-03T17:08:37Z

Tests renaming 6a1917f

adalpari marked this pull request as ready for review January 26, 2026 11:56

adalpari changed the title ~~CMM-1177 create the top post endpoint~~ CMM-1177/CMM-1178 create the top post and referrers endpoints Jan 26, 2026

adalpari requested a review from jkmassel January 26, 2026 14:02

jkmassel requested changes Jan 26, 2026

View reviewed changes

adalpari requested a review from jkmassel January 28, 2026 13:31

jkmassel reviewed Jan 29, 2026

View reviewed changes

jkmassel force-pushed the task/CMM-1177-create-the-top-post-endpoint branch from 2c589f4 to 8f31d58 Compare January 29, 2026 21:49

adalpari added 19 commits January 29, 2026 15:54

Adding top-pposts endpoint

a3fe988

Using unsigned number

a0983f1

Adding referrers endpoint

568a247

Adding the "num" field

7770b61

Adding summarize and skip_archives fields

ab6b785

Adding locale param

7b201ef

Parameterising tests

b79aa7e

Opening summarize and skip arguments

abdebcc

Allowing both responses

675bcc7

Format code

f4f5f9c

Making summarize and skip_archives default values true

331540d

Fixing parse bug and adding extra tests

0d85edf

Adding some doc comments

54a5db8

Removing useless functions

bf3918e

Fixing lint

82feb18

Adding nullability support

c67d1a1

Adding empty response parsing

035f44f

Lint

91aaa72

Adding extra checks in tests

d0ec9a0

jkmassel force-pushed the task/CMM-1177-create-the-top-post-endpoint branch from 8f31d58 to d0ec9a0 Compare January 29, 2026 22:54

Baking summary case in tests definotion

fde295e

jkmassel and others added 3 commits February 3, 2026 10:00

Cmm 1177 suggestions (#1133)

2a78e86

* Add WP.com e2e tests fx * Use `WPComLanguage` for locale * Explicitly specify `summarize` for for all requests

rename input tests

6a1917f

Merge branch 'task/CMM-1177-create-the-top-post-endpoint' of github.c…

dfbfbd6

…om:Automattic/wordpress-rs into task/CMM-1177-create-the-top-post-endpoint

Renamis with prefix and file number

0832dd6

jkmassel approved these changes Feb 3, 2026

View reviewed changes

adalpari merged commit 76cc78d into trunk Feb 4, 2026
23 checks passed

adalpari deleted the task/CMM-1177-create-the-top-post-endpoint branch February 4, 2026 14:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CMM-1177/CMM-1178 create the top post and referrers endpoints#1119

CMM-1177/CMM-1178 create the top post and referrers endpoints#1119
adalpari merged 24 commits intotrunkfrom
task/CMM-1177-create-the-top-post-endpoint

adalpari commented Jan 26, 2026 •

edited

Loading

Uh oh!

jkmassel left a comment

Uh oh!

Uh oh!

jkmassel Jan 26, 2026

Uh oh!

adalpari Jan 27, 2026

Uh oh!

crazytonyli Jan 28, 2026

Uh oh!

Uh oh!

Uh oh!

jkmassel Jan 29, 2026

Uh oh!

adalpari Jan 29, 2026 •

edited

Loading

Uh oh!

jkmassel Jan 29, 2026

Uh oh!

jkmassel commented Jan 29, 2026

Uh oh!

adalpari commented Jan 30, 2026

Uh oh!

adalpari commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

adalpari commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Implementation Details

New Files

Modified Files

API Parameters

Helper Functions

Notable Implementation Details

Uh oh!

jkmassel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jkmassel Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

adalpari Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

crazytonyli Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jkmassel Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

adalpari Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkmassel Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

jkmassel commented Jan 29, 2026

Uh oh!

adalpari commented Jan 30, 2026

Uh oh!

adalpari commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adalpari commented Jan 26, 2026 •

edited

Loading

adalpari Jan 29, 2026 •

edited

Loading