Improved formatting of generated endpoint docs.
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/3a27bfbc Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/3a27bfbc Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/3a27bfbc Branch: refs/heads/master Commit: 3a27bfbc821c605a200dc286bcc903e043f85c24 Parents: 15c5249 Author: Neil Conway <[email protected]> Authored: Mon Apr 10 14:30:06 2017 -0700 Committer: Neil Conway <[email protected]> Committed: Mon Apr 10 14:34:17 2017 -0700 ---------------------------------------------------------------------- docs/endpoints/master/api/v1.md | 2 + docs/endpoints/master/api/v1/scheduler.md | 2 + docs/endpoints/master/create-volumes.md | 5 +- docs/endpoints/master/destroy-volumes.md | 5 +- docs/endpoints/master/frameworks.md | 2 + docs/endpoints/master/health.md | 2 +- docs/endpoints/master/machine/down.md | 3 + docs/endpoints/master/machine/up.md | 3 + docs/endpoints/master/maintenance/schedule.md | 3 + docs/endpoints/master/maintenance/status.md | 3 + docs/endpoints/master/quota.md | 3 + docs/endpoints/master/redirect.md | 8 +-- docs/endpoints/master/reserve.md | 5 +- docs/endpoints/master/roles.json.md | 3 + docs/endpoints/master/roles.md | 3 + docs/endpoints/master/slaves.md | 3 + docs/endpoints/master/state-summary.md | 3 + docs/endpoints/master/state.json.md | 5 +- docs/endpoints/master/state.md | 5 +- docs/endpoints/master/tasks.json.md | 3 + docs/endpoints/master/tasks.md | 3 + docs/endpoints/master/teardown.md | 3 + docs/endpoints/master/unreserve.md | 5 +- docs/endpoints/master/weights.md | 7 +- docs/endpoints/slave/api/v1/executor.md | 4 +- src/master/http.cpp | 79 ++++++++++++++++++---- src/slave/http.cpp | 4 +- 27 files changed, 148 insertions(+), 28 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/api/v1.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/api/v1.md b/docs/endpoints/master/api/v1.md index 1d01965..2d778f3 100644 --- a/docs/endpoints/master/api/v1.md +++ b/docs/endpoints/master/api/v1.md @@ -13,8 +13,10 @@ Endpoint for API calls against the master. ### DESCRIPTION ### Returns 200 OK when the request was processed successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/api/v1/scheduler.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/api/v1/scheduler.md b/docs/endpoints/master/api/v1/scheduler.md index 4c6caf5..f029d8e 100644 --- a/docs/endpoints/master/api/v1/scheduler.md +++ b/docs/endpoints/master/api/v1/scheduler.md @@ -13,8 +13,10 @@ Endpoint for schedulers to make calls against the master. ### DESCRIPTION ### Returns 202 Accepted iff the request is accepted. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/create-volumes.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/create-volumes.md b/docs/endpoints/master/create-volumes.md index 83f85ac..c9ce39e 100644 --- a/docs/endpoints/master/create-volumes.md +++ b/docs/endpoints/master/create-volumes.md @@ -14,16 +14,19 @@ Create persistent volumes on reserved resources. ### DESCRIPTION ### Returns 202 ACCEPTED which indicates that the create operation has been validated successfully by the master. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + The request is then forwarded asynchronously to the Mesos agent where the reserved resources are located. That asynchronous message may not be delivered or creating the volumes at the agent might fail. -Please provide "slaveId" and "volumes" values designating +Please provide "slaveId" and "volumes" values describing the volumes to be created. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/destroy-volumes.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/destroy-volumes.md b/docs/endpoints/master/destroy-volumes.md index 778f797..ff82e96 100644 --- a/docs/endpoints/master/destroy-volumes.md +++ b/docs/endpoints/master/destroy-volumes.md @@ -14,16 +14,19 @@ Destroy persistent volumes. ### DESCRIPTION ### Returns 202 ACCEPTED which indicates that the destroy operation has been validated successfully by the master. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + The request is then forwarded asynchronously to the Mesos agent where the reserved resources are located. That asynchronous message may not be delivered or destroying the volumes at the agent might fail. -Please provide "slaveId" and "volumes" values designating +Please provide "slaveId" and "volumes" values describing the volumes to be destroyed. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/frameworks.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/frameworks.md b/docs/endpoints/master/frameworks.md index afb583e..1a7950a 100644 --- a/docs/endpoints/master/frameworks.md +++ b/docs/endpoints/master/frameworks.md @@ -13,8 +13,10 @@ Exposes the frameworks info. ### DESCRIPTION ### Returns 200 OK when the frameworks info was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/health.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/health.md b/docs/endpoints/master/health.md index dc1c1cd..3752a1b 100644 --- a/docs/endpoints/master/health.md +++ b/docs/endpoints/master/health.md @@ -9,7 +9,7 @@ layout: documentation > /master/health ### TL;DR; ### -Health check of the Master. +Health status of the Master. ### DESCRIPTION ### Returns 200 OK iff the Master is healthy. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/machine/down.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/machine/down.md b/docs/endpoints/master/machine/down.md index d2d5e87..a605a99 100644 --- a/docs/endpoints/master/machine/down.md +++ b/docs/endpoints/master/machine/down.md @@ -13,10 +13,13 @@ Brings a set of machines down. ### DESCRIPTION ### Returns 200 OK when the operation was successful. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + POST: Validates the request body as JSON and transitions the list of machines into DOWN mode. Currently, only machines in DRAINING mode are allowed to be brought down. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/machine/up.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/machine/up.md b/docs/endpoints/master/machine/up.md index aa2fb9b..67cfc15 100644 --- a/docs/endpoints/master/machine/up.md +++ b/docs/endpoints/master/machine/up.md @@ -13,10 +13,13 @@ Brings a set of machines back up. ### DESCRIPTION ### Returns 200 OK when the operation was successful. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + POST: Validates the request body as JSON and transitions the list of machines into UP mode. This also removes the list of machines from the maintenance schedule. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/maintenance/schedule.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/maintenance/schedule.md b/docs/endpoints/master/maintenance/schedule.md index 9244a34..d3d7154 100644 --- a/docs/endpoints/master/maintenance/schedule.md +++ b/docs/endpoints/master/maintenance/schedule.md @@ -14,10 +14,13 @@ Returns or updates the cluster's maintenance schedule. ### DESCRIPTION ### Returns 200 OK when the requested maintenance operation was performed successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + GET: Returns the current maintenance schedule as JSON. POST: Validates the request body as JSON http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/maintenance/status.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/maintenance/status.md b/docs/endpoints/master/maintenance/status.md index 5174335..1a35eba 100644 --- a/docs/endpoints/master/maintenance/status.md +++ b/docs/endpoints/master/maintenance/status.md @@ -13,10 +13,13 @@ Retrieves the maintenance status of the cluster. ### DESCRIPTION ### Returns 200 OK when the maintenance status was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + Returns an object with one list of machines per machine mode. For draining machines, this list includes the frameworks' responses to inverse offers. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/quota.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/quota.md b/docs/endpoints/master/quota.md index 229ab19..6ce7811 100644 --- a/docs/endpoints/master/quota.md +++ b/docs/endpoints/master/quota.md @@ -13,10 +13,13 @@ Gets or updates quota for roles. ### DESCRIPTION ### Returns 200 OK when the quota was queried or updated successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + GET: Returns the currently set quotas as JSON. POST: Validates the request body as JSON http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/redirect.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/redirect.md b/docs/endpoints/master/redirect.md index 3387b64..3c568e3 100644 --- a/docs/endpoints/master/redirect.md +++ b/docs/endpoints/master/redirect.md @@ -14,15 +14,13 @@ Redirects to the leading Master. ### DESCRIPTION ### Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. **NOTES:** -1. This is the recommended way to bookmark the WebUI when -running multiple Masters. -2. This is broken currently "on the cloud" (e.g. EC2) as -this will attempt to redirect to the private IP address, unless -advertise_ip points to an externally accessible IP +1. This is the recommended way to bookmark the WebUI when running multiple Masters. +2. This is broken currently "on the cloud" (e.g., EC2) as this will attempt to redirect to the private IP address, unless `advertise_ip` points to an externally accessible IP ### AUTHENTICATION ### http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/reserve.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/reserve.md b/docs/endpoints/master/reserve.md index 71cc1a9..8174027 100644 --- a/docs/endpoints/master/reserve.md +++ b/docs/endpoints/master/reserve.md @@ -14,16 +14,19 @@ Reserve resources dynamically on a specific agent. ### DESCRIPTION ### Returns 202 ACCEPTED which indicates that the reserve operation has been validated successfully by the master. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + The request is then forwarded asynchronously to the Mesos agent where the reserved resources are located. That asynchronous message may not be delivered or reserving resources at the agent might fail. -Please provide "slaveId" and "resources" values designating +Please provide "slaveId" and "resources" values describing the resources to be reserved. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/roles.json.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/roles.json.md b/docs/endpoints/master/roles.json.md index b967547..9acba2c 100644 --- a/docs/endpoints/master/roles.json.md +++ b/docs/endpoints/master/roles.json.md @@ -13,10 +13,13 @@ Information about roles. ### DESCRIPTION ### Returns 200 OK when information about roles was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + This endpoint provides information about roles as a JSON object. It returns information about every role that is on the role whitelist (if enabled), has one or more registered frameworks, http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/roles.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/roles.md b/docs/endpoints/master/roles.md index 5468b5f..de58120 100644 --- a/docs/endpoints/master/roles.md +++ b/docs/endpoints/master/roles.md @@ -13,10 +13,13 @@ Information about roles. ### DESCRIPTION ### Returns 200 OK when information about roles was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + This endpoint provides information about roles as a JSON object. It returns information about every role that is on the role whitelist (if enabled), has one or more registered frameworks, http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/slaves.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/slaves.md b/docs/endpoints/master/slaves.md index ae214d8..f9bb7ef 100644 --- a/docs/endpoints/master/slaves.md +++ b/docs/endpoints/master/slaves.md @@ -13,10 +13,13 @@ Information about agents. ### DESCRIPTION ### Returns 200 OK when the request was processed successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + This endpoint shows information about the agents which are registered in this master or recovered from registry, formatted as a JSON object. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/state-summary.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/state-summary.md b/docs/endpoints/master/state-summary.md index e29e65d..21b8703 100644 --- a/docs/endpoints/master/state-summary.md +++ b/docs/endpoints/master/state-summary.md @@ -14,10 +14,13 @@ Summary of agents, tasks, and registered frameworks in cluster. ### DESCRIPTION ### Returns 200 OK when a summary of the master's state was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + This endpoint gives a summary of the agents, tasks, and registered frameworks in the cluster as a JSON object. The information shown might be filtered based on the user http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/state.json.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/state.json.md b/docs/endpoints/master/state.json.md index 8466f7d..62a7230 100644 --- a/docs/endpoints/master/state.json.md +++ b/docs/endpoints/master/state.json.md @@ -13,12 +13,15 @@ Information about state of master. ### DESCRIPTION ### Returns 200 OK when the state of the master was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + This endpoint shows information about the frameworks, tasks, -executors and agents running in the cluster as a JSON object. +executors, and agents running in the cluster as a JSON object. The information shown might be filtered based on the user accessing the endpoint. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/state.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/state.md b/docs/endpoints/master/state.md index eba9b39..09a4782 100644 --- a/docs/endpoints/master/state.md +++ b/docs/endpoints/master/state.md @@ -13,12 +13,15 @@ Information about state of master. ### DESCRIPTION ### Returns 200 OK when the state of the master was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + This endpoint shows information about the frameworks, tasks, -executors and agents running in the cluster as a JSON object. +executors, and agents running in the cluster as a JSON object. The information shown might be filtered based on the user accessing the endpoint. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/tasks.json.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/tasks.json.md b/docs/endpoints/master/tasks.json.md index d276f27..f6b808d 100644 --- a/docs/endpoints/master/tasks.json.md +++ b/docs/endpoints/master/tasks.json.md @@ -13,10 +13,13 @@ Lists tasks from all active frameworks. ### DESCRIPTION ### Returns 200 OK when task information was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + Lists known tasks. The information shown might be filtered based on the user accessing the endpoint. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/tasks.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/tasks.md b/docs/endpoints/master/tasks.md index 64ce46c..da04c9f 100644 --- a/docs/endpoints/master/tasks.md +++ b/docs/endpoints/master/tasks.md @@ -13,10 +13,13 @@ Lists tasks from all active frameworks. ### DESCRIPTION ### Returns 200 OK when task information was queried successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + Lists known tasks. The information shown might be filtered based on the user accessing the endpoint. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/teardown.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/teardown.md b/docs/endpoints/master/teardown.md index 3ab4824..b017084 100644 --- a/docs/endpoints/master/teardown.md +++ b/docs/endpoints/master/teardown.md @@ -13,10 +13,13 @@ Tears down a running framework by shutting down all tasks/executors and removing ### DESCRIPTION ### Returns 200 OK if the framework was torn down successfully. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + Please provide a "frameworkId" value designating the running framework to tear down. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/unreserve.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/unreserve.md b/docs/endpoints/master/unreserve.md index f064239..324dcde 100644 --- a/docs/endpoints/master/unreserve.md +++ b/docs/endpoints/master/unreserve.md @@ -14,16 +14,19 @@ Unreserve resources dynamically on a specific agent. ### DESCRIPTION ### Returns 202 ACCEPTED which indicates that the unreserve operation has been validated successfully by the master. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + The request is then forwarded asynchronously to the Mesos agent where the reserved resources are located. That asynchronous message may not be delivered or unreserving resources at the agent might fail. -Please provide "slaveId" and "resources" values designating +Please provide "slaveId" and "resources" values describing the resources to be unreserved. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/master/weights.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/master/weights.md b/docs/endpoints/master/weights.md index 709b641..3c9019e 100644 --- a/docs/endpoints/master/weights.md +++ b/docs/endpoints/master/weights.md @@ -13,10 +13,13 @@ Updates weights for the specified roles. ### DESCRIPTION ### Returns 200 OK when the weights update was successful. + Returns 307 TEMPORARY_REDIRECT redirect to the leading master when current master is not the leader. + Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be found. + PUT: Validates the request body as JSON and updates the weights for the specified roles. @@ -26,7 +29,7 @@ This endpoint requires authentication iff HTTP authentication is enabled. ### AUTHORIZATION ### -Getting weight information for a certain role requires that the -current principal is authorized to get weights for the target role, +Getting weight information for a role requires that the current +principal is authorized to get weights for the target role, otherwise the entry for the target role could be silently filtered. See the authorization documentation for details. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/docs/endpoints/slave/api/v1/executor.md ---------------------------------------------------------------------- diff --git a/docs/endpoints/slave/api/v1/executor.md b/docs/endpoints/slave/api/v1/executor.md index 11cad11..5ef40e3 100644 --- a/docs/endpoints/slave/api/v1/executor.md +++ b/docs/endpoints/slave/api/v1/executor.md @@ -14,10 +14,12 @@ Endpoint for the Executor HTTP API. ### DESCRIPTION ### This endpoint is used by the executors to interact with the agent via Call/Event messages. + Returns 200 OK iff the initial SUBSCRIBE Call is successful. -This would result in a streaming response via chunked +This will result in a streaming response via chunked transfer encoding. The executors can process the response incrementally. + Returns 202 Accepted for all other Call messages iff the request is accepted. http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/src/master/http.cpp ---------------------------------------------------------------------- diff --git a/src/master/http.cpp b/src/master/http.cpp index c24bff8..0e84d36 100644 --- a/src/master/http.cpp +++ b/src/master/http.cpp @@ -439,8 +439,10 @@ string Master::Http::API_HELP() "Endpoint for API calls against the master."), DESCRIPTION( "Returns 200 OK when the request was processed successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found."), AUTHENTICATION(true), @@ -718,8 +720,10 @@ string Master::Http::SCHEDULER_HELP() "Endpoint for schedulers to make calls against the master."), DESCRIPTION( "Returns 202 Accepted iff the request is accepted.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found."), AUTHENTICATION(true), @@ -994,16 +998,19 @@ string Master::Http::CREATE_VOLUMES_HELP() DESCRIPTION( "Returns 202 ACCEPTED which indicates that the create", "operation has been validated successfully by the master.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "The request is then forwarded asynchronously to the Mesos", "agent where the reserved resources are located.", "That asynchronous message may not be delivered or", "creating the volumes at the agent might fail.", "", - "Please provide \"slaveId\" and \"volumes\" values designating", + "Please provide \"slaveId\" and \"volumes\" values describing", "the volumes to be created."), AUTHENTICATION(true), AUTHORIZATION( @@ -1161,16 +1168,19 @@ string Master::Http::DESTROY_VOLUMES_HELP() DESCRIPTION( "Returns 202 ACCEPTED which indicates that the destroy", "operation has been validated successfully by the master.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "The request is then forwarded asynchronously to the Mesos", "agent where the reserved resources are located.", "That asynchronous message may not be delivered or", "destroying the volumes at the agent might fail.", "", - "Please provide \"slaveId\" and \"volumes\" values designating", + "Please provide \"slaveId\" and \"volumes\" values describing", "the volumes to be destroyed."), AUTHENTICATION(true), AUTHORIZATION( @@ -1326,8 +1336,10 @@ string Master::Http::FRAMEWORKS_HELP() TLDR("Exposes the frameworks info."), DESCRIPTION( "Returns 200 OK when the frameworks info was queried successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found."), AUTHENTICATION(true), @@ -1930,7 +1942,7 @@ string Master::Http::HEALTH_HELP() { return HELP( TLDR( - "Health check of the Master."), + "Health status of the Master."), DESCRIPTION( "Returns 200 OK iff the Master is healthy.", "Delayed responses are also indicative of poor health."), @@ -2069,15 +2081,16 @@ string Master::Http::REDIRECT_HELP() DESCRIPTION( "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", "", "**NOTES:**", - "1. This is the recommended way to bookmark the WebUI when", + "1. This is the recommended way to bookmark the WebUI when " "running multiple Masters.", - "2. This is broken currently \"on the cloud\" (e.g. EC2) as", - "this will attempt to redirect to the private IP address, unless", - "advertise_ip points to an externally accessible IP"), + "2. This is broken currently \"on the cloud\" (e.g., EC2) as " + "this will attempt to redirect to the private IP address, unless " + "`advertise_ip` points to an externally accessible IP"), AUTHENTICATION(false)); } @@ -2145,16 +2158,19 @@ string Master::Http::RESERVE_HELP() DESCRIPTION( "Returns 202 ACCEPTED which indicates that the reserve", "operation has been validated successfully by the master.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "The request is then forwarded asynchronously to the Mesos", "agent where the reserved resources are located.", "That asynchronous message may not be delivered or", "reserving resources at the agent might fail.", "", - "Please provide \"slaveId\" and \"resources\" values designating", + "Please provide \"slaveId\" and \"resources\" values describing", "the resources to be reserved."), AUTHENTICATION(true), AUTHORIZATION( @@ -2303,10 +2319,13 @@ string Master::Http::SLAVES_HELP() "Information about agents."), DESCRIPTION( "Returns 200 OK when the request was processed successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "This endpoint shows information about the agents which are registered", "in this master or recovered from registry, formatted as a JSON", "object."), @@ -2429,10 +2448,13 @@ string Master::Http::QUOTA_HELP() "Gets or updates quota for roles."), DESCRIPTION( "Returns 200 OK when the quota was queried or updated successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "GET: Returns the currently set quotas as JSON.", "", "POST: Validates the request body as JSON", @@ -2498,16 +2520,19 @@ string Master::Http::WEIGHTS_HELP() "Updates weights for the specified roles."), DESCRIPTION( "Returns 200 OK when the weights update was successful.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "PUT: Validates the request body as JSON", "and updates the weights for the specified roles."), AUTHENTICATION(true), AUTHORIZATION( - "Getting weight information for a certain role requires that the", - "current principal is authorized to get weights for the target role,", + "Getting weight information for a role requires that the current", + "principal is authorized to get weights for the target role,", "otherwise the entry for the target role could be silently filtered.", "See the authorization documentation for details.")); } @@ -2551,12 +2576,15 @@ string Master::Http::STATE_HELP() "Information about state of master."), DESCRIPTION( "Returns 200 OK when the state of the master was queried successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "This endpoint shows information about the frameworks, tasks,", - "executors and agents running in the cluster as a JSON object.", + "executors, and agents running in the cluster as a JSON object.", "The information shown might be filtered based on the user", "accessing the endpoint.", "", @@ -3120,10 +3148,13 @@ string Master::Http::STATESUMMARY_HELP() DESCRIPTION( "Returns 200 OK when a summary of the master's state was queried", "successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "This endpoint gives a summary of the agents, tasks, and", "registered frameworks in the cluster as a JSON object.", "The information shown might be filtered based on the user", @@ -3349,10 +3380,13 @@ string Master::Http::ROLES_HELP() "Information about roles."), DESCRIPTION( "Returns 200 OK when information about roles was queried successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "This endpoint provides information about roles as a JSON object.", "It returns information about every role that is on the role", "whitelist (if enabled), has one or more registered frameworks,", @@ -3583,10 +3617,13 @@ string Master::Http::TEARDOWN_HELP() "and removing the framework."), DESCRIPTION( "Returns 200 OK if the framework was torn down successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "Please provide a \"frameworkId\" value designating the running", "framework to tear down."), AUTHENTICATION(true), @@ -3741,10 +3778,13 @@ string Master::Http::TASKS_HELP() "Lists tasks from all active frameworks."), DESCRIPTION( "Returns 200 OK when task information was queried successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "Lists known tasks.", "The information shown might be filtered based on the user", "accessing the endpoint.", @@ -4057,10 +4097,13 @@ string Master::Http::MAINTENANCE_SCHEDULE_HELP() DESCRIPTION( "Returns 200 OK when the requested maintenance operation was performed", "successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "GET: Returns the current maintenance schedule as JSON.", "", "POST: Validates the request body as JSON", @@ -4249,10 +4292,13 @@ string Master::Http::MACHINE_DOWN_HELP() "Brings a set of machines down."), DESCRIPTION( "Returns 200 OK when the operation was successful.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "POST: Validates the request body as JSON and transitions", " the list of machines into DOWN mode. Currently, only", " machines in DRAINING mode are allowed to be brought down."), @@ -4385,10 +4431,13 @@ string Master::Http::MACHINE_UP_HELP() "Brings a set of machines back up."), DESCRIPTION( "Returns 200 OK when the operation was successful.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "POST: Validates the request body as JSON and transitions", " the list of machines into UP mode. This also removes", " the list of machines from the maintenance schedule."), @@ -4520,10 +4569,13 @@ string Master::Http::MAINTENANCE_STATUS_HELP() "Retrieves the maintenance status of the cluster."), DESCRIPTION( "Returns 200 OK when the maintenance status was queried successfully.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "Returns an object with one list of machines per machine mode.", "For draining machines, this list includes the frameworks' responses", "to inverse offers.", @@ -4641,16 +4693,19 @@ string Master::Http::UNRESERVE_HELP() DESCRIPTION( "Returns 202 ACCEPTED which indicates that the unreserve", "operation has been validated successfully by the master.", + "", "Returns 307 TEMPORARY_REDIRECT redirect to the leading master when", "current master is not the leader.", + "", "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot be", "found.", + "", "The request is then forwarded asynchronously to the Mesos", "agent where the reserved resources are located.", "That asynchronous message may not be delivered or", "unreserving resources at the agent might fail.", "", - "Please provide \"slaveId\" and \"resources\" values designating", + "Please provide \"slaveId\" and \"resources\" values describing", "the resources to be unreserved."), AUTHENTICATION(true), AUTHORIZATION( http://git-wip-us.apache.org/repos/asf/mesos/blob/3a27bfbc/src/slave/http.cpp ---------------------------------------------------------------------- diff --git a/src/slave/http.cpp b/src/slave/http.cpp index b07ce7c..b78854b 100644 --- a/src/slave/http.cpp +++ b/src/slave/http.cpp @@ -607,10 +607,12 @@ string Slave::Http::EXECUTOR_HELP() { DESCRIPTION( "This endpoint is used by the executors to interact with the", "agent via Call/Event messages.", + "", "Returns 200 OK iff the initial SUBSCRIBE Call is successful.", - "This would result in a streaming response via chunked", + "This will result in a streaming response via chunked", "transfer encoding. The executors can process the response", "incrementally.", + "", "Returns 202 Accepted for all other Call messages iff the", "request is accepted."), AUTHENTICATION(false));
