Skip to content

Commit 2591445

Browse files
rodberrodber
committed
update API
1 parent eb8c77a commit 2591445

File tree

4 files changed

+87
-319
lines changed

4 files changed

+87
-319
lines changed

‎api/README.md‎

Lines changed: 87 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,133 @@
1+
---
2+
sidebarDepth: 3
3+
---
4+
15
# HTTP API
26

3-
xrDebug HTTP API standard defines a language-agnostic web service as variable introspection is generated on client-side.
7+
The HTTP API provides a RESTful interface to the server. See the [openapi.yml](https://raw.githubusercontent.com/xrdebug/xrdebug/refs/heads/3.0/api/openapi.yml) file for alternative API documentation.
8+
9+
## Endpoints
10+
11+
### GET /
12+
13+
To access the web interface, open a web browser and navigate to the server's root URL. The server will serve the web interface.
14+
15+
```sh
16+
open http://localhost:27420
17+
```
18+
19+
### POST /messages
20+
21+
Sends a message to the server.
422

5-
Following examples use [curl](https://curl.se/) to issue HTTP requests to xrDebug API.
23+
**Parameters:**
624

7-
## Create debug message
25+
All parameters are optional, but at least one is required.
826

9-
`POST /messages`
27+
- `body`: The message body.
28+
- `emote`: The message type (default: `info`).
29+
- `file_line`: The line number.
30+
- `file_path`: The file path.
31+
- `id`: The message ID.
32+
- `topic`: The message topic.
1033

11-
When creating a debug message it will be streamed to xrDebug window.
34+
**Responses:**
1235

13-
All parameters are optional: `body`, `emote`, `file_line`, `file_path`, `id`, `topic` (but at least one is required).
36+
- `200 OK`: Message sent.
37+
- `400 Bad Request`: Invalid request.
1438

1539
```sh
1640
curl --fail -X POST \
1741
--data "body=My message" \
1842
--data "file_path=file" \
1943
--data "file_line=1" \
20-
http://127.0.0.1:27420/messages
44+
http://localhost:27420/messages
2145
```
2246

23-
## Create pause
47+
### POST /pauses
2448

25-
`POST /pauses`
49+
Creates a pause lock.
2650

27-
When creating a pause, a lock for the given id will be created. When the helper sends `xri()->pause()` the debugger creates a lock with `{"stop":false}` contents.
51+
**Parameters:**
2852

29-
Requires `id`, supports optional body fields: `body`, `emote`, `file_line`, `file_path`, `topic`.
53+
- `id`: The ID of the pause lock.
3054

31-
```sh
32-
curl --fail -X POST \
33-
--data "id=b1cabc9a-145f-11ee-be56-0242ac120002" \
34-
http://127.0.0.1:27420/pauses
35-
```
55+
The following parameters are optional:
3656

37-
## Get pause
57+
- `body`: The message body.
58+
- `emote`: The message type (default: `info`).
59+
- `file_line`: The line number.
60+
- `file_path`: The file path.
61+
- `topic`: The message topic
3862

39-
`GET /pauses/{id}`
63+
**Responses:**
4064

41-
If a pause exists it means that execution is paused for the given id. The helper which called `xri()->pause()` should sleep/wait while the pause exists. If pause contents are `{"stop":false}` the id is paused, if contents are `{"stop":true}` the id is stopped.
65+
- `201 Created`: Lock created `Location: /pauses/{id}`.
66+
- `409 Conflict`: Lock already exists.
4267

4368
```sh
44-
curl --fail -X GET \
45-
http://127.0.0.1:27420/pauses/b1cabc9a-145f-11ee-be56-0242ac120002
69+
curl --fail -X POST --data "id=123" http://localhost:27420/pauses
4670
```
4771

48-
## Delete pause
72+
### GET /pauses/{id}
73+
74+
Retrieves the status of an existing pause lock.
75+
76+
**Parameters:**
4977

50-
`DELETE /pauses/{id}`
78+
- `id` (path): The ID of the pause lock.
5179

52-
When deleting a pause the lock previously created will be removed, which will enable client library to continue code execution.
80+
**Responses:**
81+
82+
- `200 OK`: Returns the pause lock (JSON).
83+
- `404 Not Found`: Lock not found.
5384

5485
```sh
55-
curl --fail -X DELETE \
56-
http://127.0.0.1:27420/pauses/b1cabc9a-145f-11ee-be56-0242ac120002
86+
curl --fail -X GET http://localhost:27420/pauses/123
5787
```
5888

59-
## Update pause (stop execution)
89+
### DELETE /pauses/{id}
90+
91+
Deletes a pause lock.
92+
93+
**Parameters:**
94+
95+
- `id` (path): The ID of the pause lock.
6096

61-
`PATCH /pauses/{id}`
97+
**Responses:**
6298

63-
When updating a pause it will update the pause to a full stop. GET requests will return `{"stop":true}`. The helper which called `xri()->pause()` should stop execution once the pause was updated to stop code execution.
99+
- `204 No Content`: Lock deleted.
100+
- `404 Not Found`: Lock not found.
64101

65102
```sh
66-
curl --fail -X PATCH \
67-
http://127.0.0.1:27420/pauses/b1cabc9a-145f-11ee-be56-0242ac120002
103+
curl --fail -X DELETE http://localhost:27420/pauses/123
68104
```
69105

70-
## Request signing
106+
### PATCH /pauses/{id}
107+
108+
Updates a pause lock status to `stop: true`.
109+
110+
**Parameters:**
111+
112+
- `id` (path): The ID of the pause lock.
71113

72-
When using sign verification (`-v` option) requests must add the `X-Signature` header.
114+
**Responses:**
73115

74-
First, sign the data fields:
116+
- `200 OK`: Lock updated, returns the pause lock (JSON).
117+
- `404 Not Found`: Lock not found.
75118

76-
```php
77-
$serialize = serialize($data);
78-
$sign = $privateKey->sign($serialize);
79-
$signature = base64_encode($sign);
119+
```sh
120+
curl --fail -X PATCH http://localhost:27420/pauses/123
80121
```
81122

82-
Then pass the signature header:
123+
### GET /stream
124+
125+
Establishes a Server-Sent Events (SSE) connection.
126+
127+
**Responses:**
128+
129+
- `200 OK`: Returns the SSE stream.
83130

84131
```sh
85-
curl --fail -X POST \
86-
--data "body=My signed message" \
87-
--data "file_path=file" \
88-
--data "file_line=1" \
89-
-H "X-Signature: <signature>" \
90-
http://127.0.0.1:27420/messages
132+
curl --fail -X GET http://localhost:27420/stream
91133
```

‎api/naming.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,4 @@
22

33
return [
44
'README.md' => 'HTTP API',
5-
'spec.md' => 'Specification',
65
];

‎api/sorting.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,4 @@
22

33
return [
44
'README.md',
5-
'spec.md'
65
];

0 commit comments

Comments
 (0)