# 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.