Skip to content

Commit 118cd0a

Browse files
emdashcodesemdashcodesgziolo
authored
Add category listing endpoints for the REST API (#120)
* add: category listing endpoints for the REST API * update: back out permissions check changes Co-authored-by: emdashcodes <emdashcodes@git.wordpress.org> Co-authored-by: gziolo <gziolo@git.wordpress.org>
1 parent e8d0efd commit 118cd0a

File tree

4 files changed

+885
-0
lines changed

4 files changed

+885
-0
lines changed

‎docs/5.rest-api.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,99 @@ curl https://example.com/wp-json/wp/v2/abilities
107107
]
108108
```
109109

110+
## List Categories
111+
112+
### Definition
113+
114+
`GET /wp/v2/abilities/categories`
115+
116+
### Arguments
117+
118+
- `page` _(integer)_: Current page of the collection. Default: `1`.
119+
- `per_page` _(integer)_: Maximum number of items to return per page. Default: `50`, Maximum: `100`.
120+
121+
### Example Request
122+
123+
```bash
124+
curl -u 'USERNAME:APPLICATION_PASSWORD' \
125+
https://example.com/wp-json/wp/v2/abilities/categories
126+
```
127+
128+
### Example Response
129+
130+
```json
131+
[
132+
{
133+
"slug": "data-retrieval",
134+
"label": "Data Retrieval",
135+
"description": "Abilities that retrieve and return data from the WordPress site.",
136+
"meta": {},
137+
"_links": {
138+
"self": [
139+
{
140+
"href": "https://example.com/wp-json/wp/v2/abilities/categories/data-retrieval"
141+
}
142+
],
143+
"collection": [
144+
{
145+
"href": "https://example.com/wp-json/wp/v2/abilities/categories"
146+
}
147+
],
148+
"abilities": [
149+
{
150+
"href": "https://example.com/wp-json/wp/v2/abilities?category=data-retrieval"
151+
}
152+
]
153+
}
154+
}
155+
]
156+
```
157+
158+
## Retrieve a Category
159+
160+
### Definition
161+
162+
`GET /wp/v2/abilities/categories/{slug}`
163+
164+
### Arguments
165+
166+
- `slug` _(string)_: The unique slug of the category.
167+
168+
### Example Request
169+
170+
```bash
171+
curl -u 'USERNAME:APPLICATION_PASSWORD' \
172+
https://example.com/wp-json/wp/v2/abilities/categories/data-retrieval
173+
```
174+
175+
### Example Response
176+
177+
```json
178+
{
179+
"slug": "data-retrieval",
180+
"label": "Data Retrieval",
181+
"description": "Abilities that retrieve and return data from the WordPress site.",
182+
"meta": {},
183+
"_links": {
184+
"self": [
185+
{
186+
"href": "https://example.com/wp-json/wp/v2/abilities/categories/data-retrieval"
187+
}
188+
],
189+
"collection": [
190+
{
191+
"href": "https://example.com/wp-json/wp/v2/abilities/categories"
192+
}
193+
],
194+
"abilities": [
195+
{
196+
"href": "https://example.com/wp-json/wp/v2/abilities?category=data-retrieval"
197+
}
198+
]
199+
}
200+
}
201+
```
202+
110203
## Retrieve an Ability
111204

112205
### Definition
@@ -247,5 +340,6 @@ The API returns standard WordPress REST API error responses with these common co
247340
- `ability_invalid_output` - output validation failed according to the ability's schema.
248341
- `ability_invalid_execute_callback` - the ability's execute callback is not callable.
249342
- `rest_ability_not_found` - the requested ability is not registered.
343+
- `rest_category_not_found` - the requested category is not registered.
250344
- `rest_ability_invalid_method` - the requested HTTP method is not allowed for executing the selected ability (e.g., using GET on a read-only ability, or POST on a regular ability).
251345
- `rest_ability_cannot_execute` - the ability cannot be executed due to insufficient permissions.

‎includes/rest-api/class-wp-rest-abilities-init.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ class WP_REST_Abilities_Init {
2424
public static function register_routes(): void {
2525
require_once __DIR__ . '/endpoints/class-wp-rest-abilities-run-controller.php';
2626
require_once __DIR__ . '/endpoints/class-wp-rest-abilities-list-controller.php';
27+
require_once __DIR__ . '/endpoints/class-wp-rest-abilities-categories-controller.php';
28+
29+
$categories_controller = new WP_REST_Abilities_Categories_Controller();
30+
$categories_controller->register_routes();
2731

2832
$run_controller = new WP_REST_Abilities_Run_Controller();
2933
$run_controller->register_routes();

0 commit comments

Comments
 (0)