69 lines
2.7 KiB
Markdown
69 lines
2.7 KiB
Markdown
# HTTP API Reference
|
|
|
|
Base: HTTP over a unix-domain socket. Example using curl: `curl --unix-socket /path/to/socket -X POST http://localhost/<path>`
|
|
|
|
1) GET /status
|
|
|
|
- Response: 200 OK
|
|
- Body: JSON `{ "ok": true }`
|
|
|
|
2) POST /validate
|
|
|
|
- Request JSON:
|
|
|
|
```json
|
|
{
|
|
"config_name": "example",
|
|
"timestamp": 1234567890
|
|
}
|
|
```
|
|
|
|
- Behavior: validates the fragment file named by `config_name` and `timestamp` under the agent's internal subdirectory inside the configured nginx config directory. Delegates to `ValidateCommand::validate`.
|
|
- Success: 200 OK, body is `[rc, output]` tuple serialized as JSON (actual shape is `(i32, String)` returned from the command; examine responses for exact formatting).
|
|
- Error cases:
|
|
- 400 Bad Request: invalid or malformed JSON
|
|
- 500 Internal Server Error: validation error or missing fragment file
|
|
|
|
- Request JSON:
|
|
|
|
```json
|
|
{
|
|
"config_name": "example",
|
|
"timestamp": 1234567890
|
|
}
|
|
```
|
|
|
|
- Behavior: validates the fragment file named by `config_name` and `timestamp` under the agent's internal subdirectory inside the configured nginx config directory. Delegates to `ValidateCommand::validate`.
|
|
- Success: 200 OK, body is a JSON array `[rc, output]` where `rc` is the integer return code and `output` is the combined stdout/stderr string from the validation command (the command returns an `(i32, String)` tuple).
|
|
- Error cases:
|
|
- 400 Bad Request: invalid or malformed JSON
|
|
- 500 Internal Server Error: validation error or missing fragment file
|
|
|
|
3) POST /validate_and_reload
|
|
|
|
- Request JSON same as `/validate`.
|
|
- Behavior: runs validation and, on success, attempts to reload nginx. Returns an object with `rc` and `ro` (return code and combined stdout/stderr output).
|
|
- Success: 200 OK with body: `{ "rc": <int>, "ro": "<output>" }`
|
|
- Errors: 400 for malformed JSON, 500 if the validate-and-reload command fails (body presents error text).
|
|
|
|
4) POST /write_config
|
|
|
|
- Request JSON:
|
|
|
|
```json
|
|
{
|
|
"config_name": "example",
|
|
"timestamp": 1234567890,
|
|
"content": "server { ... }"
|
|
}
|
|
```
|
|
|
|
- Behavior: writes the provided `content` into an agent-managed fragment file named from `config_name` and `timestamp` in the internal subdirectory under `nginx_config_dir`.
|
|
- Success: 200 OK with empty body
|
|
- Error: 400 for malformed JSON, 500 if writing the file fails
|
|
|
|
Notes
|
|
|
|
- The agent expects callers to choose a `config_name` and `timestamp` that together form a unique filename. The concrete filename encoding is performed by `commands::run::to_file_name` in source.
|
|
- On validation failures the returned output often contains the full `nginx -t` output; inspect `ro` or the returned JSON error messages.
|