YANPM/apps/agent/doc/api.md

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:

   {
     "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:

   {
      "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:

   {
     "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.