Use abilities categories in rest-api - #10402

Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom
aaronjorbin:64098/update-name
Open

Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom
aaronjorbin:64098/update-name

Conversation

@aaronjorbin

@aaronjorbinaaronjorbin commented Oct 23, 2025

Copy link
Copy Markdown
Member

Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032

Trac ticket: https://core.trac.wordpress.org/ticket/64098

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

@github-actions

github-actionsBot commented Oct 23, 2025•
edited
Loading

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@github-actions

github-actionsBot commented Oct 23, 2025

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

@gziolo

gziolo commented Oct 23, 2025

Copy link
Copy Markdown
Member

Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.

@aaronjorbin

aaronjorbin commented Oct 23, 2025

Copy link
Copy Markdown
MemberAuthor

I think so since the name of the resource is ability categories, not categories.

@TimothyBJacobs

TimothyBJacobs commented Oct 23, 2025

Copy link
Copy Markdown
Member

IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.

JasonTheAdams
JasonTheAdams reviewed Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
),
'abilities' => array(
'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),

@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.

@aaronjorbinaaronjorbinNov 7, 2025

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215

@gziologzioloNov 8, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.

@aaronjorbin

aaronjorbin commented Nov 3, 2025

Copy link
Copy Markdown
MemberAuthor

My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.

I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.

@aaronjorbin

aaronjorbin commented Nov 7, 2025

Copy link
Copy Markdown
MemberAuthor

In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.

JasonTheAdams
JasonTheAdams approved these changes Nov 8, 2025
View reviewed changes

@JasonTheAdamsJasonTheAdams left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍

@TimothyBJacobs

TimothyBJacobs commented Nov 10, 2025

Copy link
Copy Markdown
Member

I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.

Agreed.

My thinking with being specific is that it prevents any confusion between categories and abilities categories.

Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:

/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:

/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories

I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.

@aaronjorbin

aaronjorbin commented Nov 10, 2025

Copy link
Copy Markdown
MemberAuthor

Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:

/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:

/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.

@TimothyBJacobs

TimothyBJacobs commented Nov 10, 2025

Copy link
Copy Markdown
Member

The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.

These are not categories, they are ability categories.

I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".

Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.

The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.

But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.

@aaronjorbin

aaronjorbin commented Nov 10, 2025

Copy link
Copy Markdown
MemberAuthor

I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".

The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.

But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.

Thanks, I'll open a new PR to fix that.

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo
1 more reviewer
@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Use abilities categories in rest-api - #10402
Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Open
Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Conversation
@aaronjorbin
@aaronjorbinaaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032
Trac ticket: https://core.trac.wordpress.org/ticket/64098
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
@github-actions
github-actionsBot
commented
Oct 23, 2025•

edited

Loading

Copy link


Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.
Core Committers: Use this line as a base for the props when committing in SVN:
Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.
@github-actions
github-actionsBot
commented
Oct 23, 2025

Copy link


Copy Markdown

Test using WordPress Playground
The changes in this pull request can previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.
Some things to be aware of
  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.
Test this pull request with WordPress Playground.
@gziolo
gziolo
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.
@aaronjorbin
aaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

MemberAuthor
I think so since the name of the resource is ability categories, not categories.
@TimothyBJacobs
TimothyBJacobs
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.
JasonTheAdams
JasonTheAdams
reviewed
Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
 ),
 'abilities' => array(
 'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
 'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),
@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.
@aaronjorbinaaronjorbinNov 7, 2025

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215
@gziologzioloNov 8, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.
@aaronjorbin
aaronjorbin
commented
Nov 3, 2025

Copy link


Copy Markdown

MemberAuthor
My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
@aaronjorbin
aaronjorbin
commented
Nov 7, 2025

Copy link


Copy Markdown

MemberAuthor
In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.
JasonTheAdams
JasonTheAdams
approved these changes
Nov 8, 2025
View reviewed changes
@JasonTheAdamsJasonTheAdams
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
Agreed.
My thinking with being specific is that it prevents any confusion between categories and abilities categories.
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories
I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.
These are not categories, they are ability categories.
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.
The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
Thanks, I'll open a new PR to fix that.
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo

1 more reviewer

@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Use abilities categories in rest-api - #10402
Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Open
Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Conversation
@aaronjorbin
@aaronjorbinaaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032
Trac ticket: https://core.trac.wordpress.org/ticket/64098
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
@github-actions
github-actionsBot
commented
Oct 23, 2025•

edited

Loading

Copy link


Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.
Core Committers: Use this line as a base for the props when committing in SVN:
Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.
@github-actions
github-actionsBot
commented
Oct 23, 2025

Copy link


Copy Markdown

Test using WordPress Playground
The changes in this pull request can previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.
Some things to be aware of
  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.
Test this pull request with WordPress Playground.
@gziolo
gziolo
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.
@aaronjorbin
aaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

MemberAuthor
I think so since the name of the resource is ability categories, not categories.
@TimothyBJacobs
TimothyBJacobs
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.
JasonTheAdams
JasonTheAdams
reviewed
Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
 ),
 'abilities' => array(
 'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
 'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),
@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.
@aaronjorbinaaronjorbinNov 7, 2025

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215
@gziologzioloNov 8, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.
@aaronjorbin
aaronjorbin
commented
Nov 3, 2025

Copy link


Copy Markdown

MemberAuthor
My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
@aaronjorbin
aaronjorbin
commented
Nov 7, 2025

Copy link


Copy Markdown

MemberAuthor
In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.
JasonTheAdams
JasonTheAdams
approved these changes
Nov 8, 2025
View reviewed changes
@JasonTheAdamsJasonTheAdams
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
Agreed.
My thinking with being specific is that it prevents any confusion between categories and abilities categories.
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories
I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.
These are not categories, they are ability categories.
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.
The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
Thanks, I'll open a new PR to fix that.
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo

1 more reviewer

@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Use abilities categories in rest-api - #10402
Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Open
Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Conversation
@aaronjorbin
@aaronjorbinaaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032
Trac ticket: https://core.trac.wordpress.org/ticket/64098
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
@github-actions
github-actionsBot
commented
Oct 23, 2025•

edited

Loading

Copy link


Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.
Core Committers: Use this line as a base for the props when committing in SVN:
Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.
@github-actions
github-actionsBot
commented
Oct 23, 2025

Copy link


Copy Markdown

Test using WordPress Playground
The changes in this pull request can previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.
Some things to be aware of
  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.
Test this pull request with WordPress Playground.
@gziolo
gziolo
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.
@aaronjorbin
aaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

MemberAuthor
I think so since the name of the resource is ability categories, not categories.
@TimothyBJacobs
TimothyBJacobs
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.
JasonTheAdams
JasonTheAdams
reviewed
Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
 ),
 'abilities' => array(
 'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
 'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),
@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.
@aaronjorbinaaronjorbinNov 7, 2025

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215
@gziologzioloNov 8, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.
@aaronjorbin
aaronjorbin
commented
Nov 3, 2025

Copy link


Copy Markdown

MemberAuthor
My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
@aaronjorbin
aaronjorbin
commented
Nov 7, 2025

Copy link


Copy Markdown

MemberAuthor
In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.
JasonTheAdams
JasonTheAdams
approved these changes
Nov 8, 2025
View reviewed changes
@JasonTheAdamsJasonTheAdams
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
Agreed.
My thinking with being specific is that it prevents any confusion between categories and abilities categories.
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories
I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.
These are not categories, they are ability categories.
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.
The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
Thanks, I'll open a new PR to fix that.
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo

1 more reviewer

@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Use abilities categories in rest-api - #10402
Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Open
Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Conversation
@aaronjorbin
@aaronjorbinaaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032
Trac ticket: https://core.trac.wordpress.org/ticket/64098
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
@github-actions
github-actionsBot
commented
Oct 23, 2025•

edited

Loading

Copy link


Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.
Core Committers: Use this line as a base for the props when committing in SVN:
Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.
@github-actions
github-actionsBot
commented
Oct 23, 2025

Copy link


Copy Markdown

Test using WordPress Playground
The changes in this pull request can previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.
Some things to be aware of
  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.
Test this pull request with WordPress Playground.
@gziolo
gziolo
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.
@aaronjorbin
aaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

MemberAuthor
I think so since the name of the resource is ability categories, not categories.
@TimothyBJacobs
TimothyBJacobs
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.
JasonTheAdams
JasonTheAdams
reviewed
Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
 ),
 'abilities' => array(
 'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
 'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),
@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.
@aaronjorbinaaronjorbinNov 7, 2025

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215
@gziologzioloNov 8, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.
@aaronjorbin
aaronjorbin
commented
Nov 3, 2025

Copy link


Copy Markdown

MemberAuthor
My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
@aaronjorbin
aaronjorbin
commented
Nov 7, 2025

Copy link


Copy Markdown

MemberAuthor
In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.
JasonTheAdams
JasonTheAdams
approved these changes
Nov 8, 2025
View reviewed changes
@JasonTheAdamsJasonTheAdams
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
Agreed.
My thinking with being specific is that it prevents any confusion between categories and abilities categories.
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories
I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.
These are not categories, they are ability categories.
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.
The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
Thanks, I'll open a new PR to fix that.
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo

1 more reviewer

@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Use abilities categories in rest-api - #10402
Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Open
Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Conversation
@aaronjorbin
@aaronjorbinaaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032
Trac ticket: https://core.trac.wordpress.org/ticket/64098
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
@github-actions
github-actionsBot
commented
Oct 23, 2025•

edited

Loading

Copy link


Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.
Core Committers: Use this line as a base for the props when committing in SVN:
Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.
@github-actions
github-actionsBot
commented
Oct 23, 2025

Copy link


Copy Markdown

Test using WordPress Playground
The changes in this pull request can previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.
Some things to be aware of
  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.
Test this pull request with WordPress Playground.
@gziolo
gziolo
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.
@aaronjorbin
aaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

MemberAuthor
I think so since the name of the resource is ability categories, not categories.
@TimothyBJacobs
TimothyBJacobs
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.
JasonTheAdams
JasonTheAdams
reviewed
Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
 ),
 'abilities' => array(
 'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
 'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),
@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.
@aaronjorbinaaronjorbinNov 7, 2025

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215
@gziologzioloNov 8, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.
@aaronjorbin
aaronjorbin
commented
Nov 3, 2025

Copy link


Copy Markdown

MemberAuthor
My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
@aaronjorbin
aaronjorbin
commented
Nov 7, 2025

Copy link


Copy Markdown

MemberAuthor
In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.
JasonTheAdams
JasonTheAdams
approved these changes
Nov 8, 2025
View reviewed changes
@JasonTheAdamsJasonTheAdams
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
Agreed.
My thinking with being specific is that it prevents any confusion between categories and abilities categories.
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories
I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.
These are not categories, they are ability categories.
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.
The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
Thanks, I'll open a new PR to fix that.
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo

1 more reviewer

@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Use abilities categories in rest-api - #10402
Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Open
Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Conversation
@aaronjorbin
@aaronjorbinaaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032
Trac ticket: https://core.trac.wordpress.org/ticket/64098
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
@github-actions
github-actionsBot
commented
Oct 23, 2025•

edited

Loading

Copy link


Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.
Core Committers: Use this line as a base for the props when committing in SVN:
Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.
@github-actions
github-actionsBot
commented
Oct 23, 2025

Copy link


Copy Markdown

Test using WordPress Playground
The changes in this pull request can previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.
Some things to be aware of
  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.
Test this pull request with WordPress Playground.
@gziolo
gziolo
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.
@aaronjorbin
aaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

MemberAuthor
I think so since the name of the resource is ability categories, not categories.
@TimothyBJacobs
TimothyBJacobs
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.
JasonTheAdams
JasonTheAdams
reviewed
Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
 ),
 'abilities' => array(
 'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
 'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),
@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.
@aaronjorbinaaronjorbinNov 7, 2025

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215
@gziologzioloNov 8, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.
@aaronjorbin
aaronjorbin
commented
Nov 3, 2025

Copy link


Copy Markdown

MemberAuthor
My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
@aaronjorbin
aaronjorbin
commented
Nov 7, 2025

Copy link


Copy Markdown

MemberAuthor
In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.
JasonTheAdams
JasonTheAdams
approved these changes
Nov 8, 2025
View reviewed changes
@JasonTheAdamsJasonTheAdams
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
Agreed.
My thinking with being specific is that it prevents any confusion between categories and abilities categories.
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories
I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.
These are not categories, they are ability categories.
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.
The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
Thanks, I'll open a new PR to fix that.
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo

1 more reviewer

@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Use abilities categories in rest-api - #10402
Open
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Open
Use abilities categories in rest-api#10402
aaronjorbin wants to merge 2 commits into
WordPress:trunkfrom 
aaronjorbin:64098/update-name
Conversation
@aaronjorbin
@aaronjorbinaaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Follow up to https://core.trac.wordpress.org/changeset/61045 and https://core.trac.wordpress.org/changeset/61032
Trac ticket: https://core.trac.wordpress.org/ticket/64098
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.
@github-actions
github-actionsBot
commented
Oct 23, 2025•

edited

Loading

Copy link


Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.
Core Committers: Use this line as a base for the props when committing in SVN:
Props jorbin, jason_the_adams, gziolo, timothyblynjacobs.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.
@github-actions
github-actionsBot
commented
Oct 23, 2025

Copy link


Copy Markdown

Test using WordPress Playground
The changes in this pull request can previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.
Some things to be aware of
  • The Plugin and Theme Directories cannot be accessed within Playground.
  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.
Test this pull request with WordPress Playground.
@gziolo
gziolo
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
Is this stricly necessary? I followed the feedback from @TimothyBJacobs (#9410 (comment)) when renaming the route and controller.
@aaronjorbin
aaronjorbin
commented
Oct 23, 2025

Copy link


Copy Markdown

MemberAuthor
I think so since the name of the resource is ability categories, not categories.
@TimothyBJacobs
TimothyBJacobs
commented
Oct 23, 2025

Copy link


Copy Markdown

Member
IMO it being within the wp-abilities/v1 namespace means we don't need to, and shouldn't, duplicate the naming here.
JasonTheAdams
JasonTheAdams
reviewed
Oct 27, 2025
View reviewed changes
Comment thread...p-includes/rest-api/endpoints/class-wp-rest-abilities-v1-abilities-categories-controller.php
 ),
 'abilities' => array(
 'href' => rest_url( sprintf( '%s/abilities?category=%s', $this->namespace, $category->get_slug() ) ),
 'href' => rest_url( sprintf( '%s/abilities?ability_category=%s', $this->namespace, $category->get_slug() ) ),
@JasonTheAdamsJasonTheAdamsOct 27, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this parameter already get changed in another PR? I'm not seeing this change in this PR.
@aaronjorbinaaronjorbinNov 7, 2025

Copy link


Copy Markdown

MemberAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It has not been changed in trunk since being committed. https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php#L215
@gziologzioloNov 8, 2025

Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as category param here, unless you also want to change the filtering in the list controller.
@aaronjorbin
aaronjorbin
commented
Nov 3, 2025

Copy link


Copy Markdown

MemberAuthor
My thinking with being specific is that it prevents any confusion between categories and abilities categories. This was what I view as the consensus reached in #9410. While this endpoint is inside the wp-abilities namespace, it's not duplicative since the name is abilities categories not categories. By being consistent and always using the full and accurate name, there is less of a chance to generate confusion.
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
@aaronjorbin
aaronjorbin
commented
Nov 7, 2025

Copy link


Copy Markdown

MemberAuthor
In order for thsi to make RC1, I'm planning to commit this on Monday, please get any reviews folks have in done before them.
JasonTheAdams
JasonTheAdams
approved these changes
Nov 8, 2025
View reviewed changes
@JasonTheAdamsJasonTheAdams
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it's important for us to be consistent with this. 👍
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
I think this is important to get right since this isn't something that will be easy to change after 6.9 is released.
Agreed.
My thinking with being specific is that it prevents any confusion between categories and abilities categories.
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

it prevents any confusion between categories and abilities categories
I don't think this is likely to happen. I think the segmentation provided by the namespace and the API structure is pretty different.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
Adopting a specific namespace for the API allows us to organize like endpoints and reduce duplicative naming. Ultimately, Code is Poetry, and I think APIs like:
/wp-abilities/v1/categories
/wp-abilities/v1/abilities?category=blah

Are more elegant than:
/wp-abilities/v1/ability-cateogires
/wp-abilities/v1/abilities?ability_category=blah

The problem is that it's not accurate. These are not categories, they are ability categories. Using a shortened form that is the name of something else doesn't reduce duplicative naming, it makes it inaccurate.
@TimothyBJacobs
TimothyBJacobs
commented
Nov 10, 2025

Copy link


Copy Markdown

Member
The argument I understand you to be making, is that the API namespace doesn't matter for naming, and doesn't provide any scoping. I just can't get behind that.
These are not categories, they are ability categories.
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
Most resources in this API are going to also be about abilities, and I don't want us to need to prefix every one of them with the word ability since it is already described by the namespace.
The mapping of PHP functions doesn't need to be an exact one-to-one with how they are represented in the REST API. We see this in other Core APIs like /wp/v2/types and /wp/v2/statuses. The PHP functions are referring only to "post types" and "post statuses", but they aren't included in the URL.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
@aaronjorbin
aaronjorbin
commented
Nov 10, 2025

Copy link


Copy Markdown

MemberAuthor
I'm struggling to understand what you mean by this. Yes, they are used to categorize abilities. And that should be evident by their URL including "abilities".
The consensus decided in #9410 was to name them Abilities Categories with the specific idea being "We always refer to them as Ability Categories and not merely "category"". What I'm hoping to do here is to live up to that consensus.
But even if we do look at the PHP API, we can see that the abilities portion of the symbol is to provide scoping. For example, wp_register_ability() takes a category argument, not an ability_category. The hook to register categories is wp_abilities_api_categories_init not wp_abilities_api_ability_categories_init.
Thanks, I'll open a new PR to fix that.
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@gziologzioloAwaiting requested review from gziolo

1 more reviewer

@JasonTheAdamsJasonTheAdamsJasonTheAdams approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels


None yet


Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@aaronjorbin@gziolo@TimothyBJacobs@JasonTheAdams