From fbdfecc1431f256c5a361c5df0af1d5c0655980b Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 4 Jun 2016 18:42:30 +0900 Subject: [PATCH] Add nghttpx API section --- doc/nghttpx.h2r | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/doc/nghttpx.h2r b/doc/nghttpx.h2r index a8f50b7d..8fd9430d 100644 --- a/doc/nghttpx.h2r +++ b/doc/nghttpx.h2r @@ -462,6 +462,42 @@ addresses: App.new +API ENDPOINTS +------------- + +nghttpx exposes API endpoints to manipulate it via HTTP based API. By +default, API endpoint is disabled. To enable it, add a dedicated +frontend for API using :option:`--frontend` option with "api" +parameter. All requests which come from this frontend address, will +be treated as API request. + +The following section describes available API endpoints. + +PUT /api/v1beta/backend/replace +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This API replaces the current set of backend servers with the +requested ones. The request must carry request body with method PUT +or POST. The request body must be nghttpx configuration file format. +For configuration file format, see `FILES`_ section. The line +separator inside the request body must be single LF (0x0A). +Currently, only :option:`backend <--backend>` option is parsed, the +others are simply ignored. The semantics of this API is replace the +current backend with the backend options in request body. Describe +the desired set of backend severs, and nghttpx makes it happen. If +there is no :option:`backend <--backend>` option is found in request +body, the current set of backend is replaced with the :option:`backend +<--backend>` option's default value, which is ``127.0.0.1,80``. + +The replacement is done instantly without breaking existing +connections or requests. It also avoids any process creation as is +the case with hot swapping with signals. + +The one limitation is that only numeric IP address is allowd in +:option:`backend <--backend>` in request body while non numeric +hostname is allowed in command-line or configuration file is read +using :option:`--conf`. + SEE ALSO --------