Skip to content

Commit 3cd5a7f

Browse files
pattonwebzpattonwebz
authored
Merge pull request #986 from equalizedigital/docs/issues-api
Add API documentation for the Issues API.
2 parents 21d83bc + 74141a8 commit 3cd5a7f

2 files changed

Lines changed: 444 additions & 3 deletions

File tree

‎docs/issues-api.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
# Issues API
2+
3+
This document outlines the functionality and usage of the Accessibility Checker Issues API. The API provides programmatic access to manage accessibility issues within your WordPress site.
4+
5+
**API Namespace:** `accessibility-checker/v1`
6+
**Base URL:** `/wp-json/accessibility-checker/v1/issues`
7+
8+
## Authentication
9+
10+
All API endpoints require authentication. The requesting user must have the `manage_options` capability. Requests are validated using a token or nonce via `REST_Api::check_token_or_nonce_and_capability_permissions_check`. Ensure your requests include a valid WordPress nonce or are made by an authenticated user with the appropriate permissions.
11+
12+
## Common Response Object Structure
13+
14+
Many API calls that return issue data will include objects with the following structure:
15+
16+
| Field | Type | Description |
17+
|-----------------|---------|-----------------------------------------------------------------------------|
18+
| `id` | integer | The unique identifier for the issue. |
19+
| `postid` | integer | The ID of the post associated with the issue. |
20+
| `siteid` | integer | The ID of the site (blog) where the issue occurred. |
21+
| `type` | string | The type of issue (e.g., 'error', 'warning'). |
22+
| `rule` | string | The specific accessibility rule that was violated. |
23+
| `ruletype` | string | The type of rule (e.g., 'EDAC', 'WCAG2AA'). |
24+
| `object` | string | The HTML object or element that caused the issue. |
25+
| `recordcheck` | boolean | Indicates if the record was checked. |
26+
| `created` | string | Timestamp (YYYY-MM-DD HH:MM:SS) of when the issue was created. |
27+
| `user` | integer | The user ID of the person who discovered or created the issue. |
28+
| `ignre` | boolean | Whether the issue is ignored. |
29+
| `ignre_global` | boolean | Whether the issue is ignored globally. |
30+
| `ignre_user` | integer | User ID of the user who ignored the issue (if applicable). |
31+
| `ignre_date` | string | Timestamp (YYYY-MM-DD HH:MM:SS) of when the issue was ignored (if applicable). |
32+
| `ignre_comment` | string | Comment provided when ignoring the issue (if applicable). |
33+
| `post_title` | string | The title of the post associated with the issue. |
34+
| `post_permalink`| string | The permalink to the post associated with the issue. |
35+
| `discoverer_username` | string | The display name of the user who discovered the issue. |
36+
| `ignre_username`| string | The display name of the user who ignored the issue (if applicable). |
37+
| `meta` | object | Contains metadata for the response. |
38+
| `meta.links` | object | Contains HATEOAS links (`self`, `collection`). |
39+
| `meta.pagination`| object | Contains pagination details (`page`, `per_page`, `total_pages`). |
40+
41+
## Error Responses
42+
43+
Errors are returned using standard WordPress `WP_Error` objects. Common error codes include:
44+
45+
* `rest_issue_invalid_id`: Invalid issue ID provided. (Status: 404)
46+
* `rest_issue_delete_failed`: Failed to delete the issue. (Status: 500)
47+
* `rest_issue_invalid_fields`: Missing required fields for creation. (Status: 400)
48+
* `rest_issue_invalid_post`: Invalid post ID provided. (Status: 400)
49+
* Generic authentication/authorization errors if permissions are not met. (Status: 401 or 403)
50+
51+
## Endpoints
52+
53+
### GET /issues
54+
55+
Retrieves a paginated list of issues.
56+
57+
**Example Request:**
58+
```
59+
GET /wp-json/accessibility-checker/v1/issues?per_page=5&page=2
60+
```
61+
62+
**Query Parameters:**
63+
64+
| Parameter | Type | Default | Description |
65+
|-----------|---------|---------|------------------------------------------------------|
66+
| `page` | integer | 1 | Current page of the collection. |
67+
| `per_page`| integer | 10 | Maximum number of items to be returned (max 500). |
68+
| `ids` | array | [] | Optional. An array of specific issue IDs to retrieve. |
69+
70+
**Response:**
71+
* Status: `200 OK`
72+
* Headers:
73+
* `X-WP-Total`: Total number of issues.
74+
* `X-WP-TotalPages`: Total number of pages.
75+
* Body: An array of issue objects (see Common Response Object Structure).
76+
77+
### POST /issues
78+
79+
Creates a new issue.
80+
81+
**Example Request:**
82+
```json
83+
POST /wp-json/accessibility-checker/v1/issues
84+
{
85+
"postid": 1,
86+
"rule": "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail",
87+
"ruletype": "WCAG2AA",
88+
"object": "<button>Submit</button>",
89+
"user": 1
90+
}
91+
```
92+
93+
**Request Body Parameters:**
94+
95+
| Parameter | Type | Required | Description |
96+
|------------|---------|----------|--------------------------------------------------|
97+
| `postid` | integer | Yes | The ID of the post to associate the issue with. |
98+
| `rule` | string | Yes | The specific accessibility rule violated. |
99+
| `ruletype` | string | Yes | The type of rule (e.g., 'EDAC', 'WCAG2AA'). |
100+
| `object` | string | Yes | The HTML snippet or identifier of the element. |
101+
| `user` | integer | Yes | The user ID to associate with creating the issue. |
102+
103+
**Response:**
104+
* Status: `201 Created` on success.
105+
* Body:
106+
```json
107+
{
108+
"id": <inserted_issue_id>
109+
}
110+
```
111+
* Status: `400 Bad Request` if required fields are missing or invalid (e.g., `rest_issue_invalid_fields`, `rest_issue_invalid_post`).
112+
113+
### GET /issues/{id}
114+
115+
Retrieves a specific issue by its ID.
116+
117+
**Example Request:**
118+
```
119+
GET /wp-json/accessibility-checker/v1/issues/123
120+
```
121+
122+
**Path Parameters:**
123+
124+
| Parameter | Type | Description |
125+
|-----------|---------|----------------------|
126+
| `id` | integer | The ID of the issue. |
127+
128+
**Response:**
129+
* Status: `200 OK`
130+
* Body: A single issue object (see Common Response Object Structure).
131+
* Status: `404 Not Found` if the issue ID is invalid (`rest_issue_invalid_id`).
132+
133+
### PUT /issues/{id}
134+
135+
Updates an existing issue identified by its ID. This endpoint allows for modifying one or more properties of an issue.
136+
137+
**Request URL:** `PUT /wp-json/accessibility-checker/v1/issues/{id}`
138+
139+
**Authentication:** Requires the `manage_options` capability.
140+
141+
**Path Parameters:**
142+
143+
| Parameter | Type | Required | Description |
144+
|-----------|---------|----------|---------------------------|
145+
| `id` | integer | Yes | The ID of the issue to update. |
146+
147+
**Request Body Parameters:**
148+
149+
Any of the following fields can be included in the request body to update the corresponding issue property. All fields are optional.
150+
151+
| Parameter | Type | Description |
152+
|-----------------|---------|-----------------------------------------------------------------------------|
153+
| `postid` | integer | The ID of the post associated with the issue. |
154+
| `type` | string | The type of issue (e.g., "error", "warning"). |
155+
| `rule` | string | The specific accessibility rule that was violated. |
156+
| `ruletype` | string | The type of rule (e.g., "EDAC", "WCAG2AA"). |
157+
| `object` | string | The HTML object or element that caused the issue. |
158+
| `recordcheck` | boolean | Indicates if the record was checked (true/false). |
159+
| `user` | integer | The user ID of the person who discovered or created the issue. |
160+
| `ignre` | boolean | Whether the issue is ignored (true/false). |
161+
| `ignre_global` | boolean | Whether the issue is ignored globally (true/false). |
162+
| `ignre_user` | integer | User ID of the user who ignored the issue. |
163+
| `ignre_date` | string | Timestamp (YYYY-MM-DD HH:MM:SS) of when the issue was ignored. Format: date-time. |
164+
| `ignre_comment` | string | Comment provided when ignoring the issue. |
165+
166+
**Example Request:**
167+
```json
168+
PUT /wp-json/accessibility-checker/v1/issues/123
169+
{
170+
"ignre": true,
171+
"ignre_comment": "Marked as ignored due to pending content update."
172+
}
173+
```
174+
175+
**Success Response (200 OK):**
176+
177+
* Content: The full updated issue object, consistent with the "Common Response Object Structure".
178+
179+
**Error Responses:**
180+
181+
* **400 Bad Request:** If no valid fields are provided for update.
182+
```json
183+
{
184+
"code": "rest_nothing_to_update",
185+
"message": "No fields provided to update.",
186+
"data": { "status": 400 }
187+
}
188+
```
189+
* **404 Not Found:** If the issue with the specified ID does not exist.
190+
```json
191+
{
192+
"code": "rest_issue_invalid_id",
193+
"message": "Invalid issue ID.",
194+
"data": { "status": 404 }
195+
}
196+
```
197+
* **500 Internal Server Error:** If the update fails for other reasons (e.g., database error).
198+
```json
199+
{
200+
"code": "rest_issue_update_failed",
201+
"message": "Failed to update issue.",
202+
"data": { "status": 500 }
203+
}
204+
```
205+
206+
### DELETE /issues/{id}
207+
208+
Deletes an issue by its ID.
209+
210+
**Example Request:**
211+
```
212+
DELETE /wp-json/accessibility-checker/v1/issues/123
213+
```
214+
215+
**Path Parameters:**
216+
217+
| Parameter | Type | Description |
218+
|-----------|---------|----------------------|
219+
| `id` | integer | The ID of the issue. |
220+
221+
**Response:**
222+
* Status: `204 No Content` on successful deletion.
223+
* Body:
224+
```json
225+
{
226+
"success": true
227+
}
228+
```
229+
* Status: `404 Not Found` if the issue ID is invalid (`rest_issue_invalid_id`).
230+
* Status: `500 Internal Server Error` if deletion fails (`rest_issue_delete_failed`).
231+
232+
### GET /issues/access-check
233+
234+
Checks API accessibility and permissions. This is a simple endpoint to verify that the current user/token can interact with the Issues API.
235+
236+
**Example Request:**
237+
```
238+
GET /wp-json/accessibility-checker/v1/issues/access-check
239+
```
240+
241+
**Response:**
242+
* Status: `200 OK`
243+
* Body:
244+
```json
245+
{
246+
"success": true
247+
}
248+
```
249+
250+
### GET /issues/count
251+
252+
Retrieves the count of issues, optionally filtered by a list of issue IDs.
253+
254+
**Example Request:**
255+
```
256+
GET /wp-json/accessibility-checker/v1/issues/count
257+
```
258+
or with specific IDs:
259+
```
260+
GET /wp-json/accessibility-checker/v1/issues/count?ids[]=1&ids[]=2&ids[]=5
261+
```
262+
263+
**Query Parameters:**
264+
265+
| Parameter | Type | Default | Description |
266+
|-----------|-------|---------|--------------------------------------------------|
267+
| `ids` | array | [] | Optional. An array of issue IDs to count. If empty, counts all issues. |
268+
269+
**Response:**
270+
* Status: `200 OK`
271+
* Body:
272+
```json
273+
{
274+
"count": <number_of_issues>
275+
}
276+
```

0 commit comments

Comments
 (0)