From 04c7ccacf10c6b23e1753a84b1453a17a5ebfb9c Mon Sep 17 00:00:00 2001 From: zcin Date: Fri, 5 Aug 2022 09:51:53 -0700 Subject: [PATCH] [Serve][Doc] Moves Serve REST API and Serve CLI API into separate subpages (#26914) --- doc/source/serve/package-ref.md | 175 ++------------------------------ doc/source/serve/rest_api.md | 154 ++++++++++++++++++++++++++++ doc/source/serve/serve_cli.md | 9 ++ 3 files changed, 171 insertions(+), 167 deletions(-) create mode 100644 doc/source/serve/rest_api.md create mode 100644 doc/source/serve/serve_cli.md diff --git a/doc/source/serve/package-ref.md b/doc/source/serve/package-ref.md index 77bb27ea5..4f8e24c19 100644 --- a/doc/source/serve/package-ref.md +++ b/doc/source/serve/package-ref.md @@ -49,173 +49,14 @@ .. autofunction:: ray.serve.batch(max_batch_size=10, batch_wait_timeout_s=0.0) ``` -(serve-rest-api)= +## Operational APIs -## Serve REST API +Check out the [CLI](serve-cli) and [REST API](serve-rest-api) for running, debugging, inspecting, and deploying Serve applications in production: -### REST API +```{toctree} +:maxdepth: 1 +:name: serve-non-python-api -#### `GET "/api/serve/deployments/"` - -Gets latest config that Serve has received. This config represents the current goal state for the Serve application. Starts a Serve application on the Ray cluster if it's not already running. See the [config schema](serve-rest-api-config-schema) for the response's JSON schema. - -**Example Request**: - -``` -GET /api/serve/deployments/ HTTP 1.1 -Host: http://localhost:52365/ -Accept: application/json -``` - -**Example Response**: - -```http -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "import_path": "fruit.deployment_graph", - "runtime_env": { - "working_dir": "https://github.com/ray-project/serve_config_examples/archive/HEAD.zip" - }, - "deployments": [ - {"name": "MangoStand", "user_config": {"price": 1}}, - {"name": "OrangeStand", "user_config": {"price": 2}}, - {"name": "PearStand", "user_config": {"price": 3}} - ] -} -``` - -#### `PUT "/api/serve/deployments/"` - -Declaratively deploys the Serve application. Starts Serve on the Ray cluster if it's not already running. See the [config schema](serve-rest-api-config-schema) for the request's JSON schema. - -**Example Request**: - -``` -PUT /api/serve/deployments/ HTTP 1.1 -Host: http://localhost:52365/ -Accept: application/json - -{ - "import_path": "fruit.deployment_graph", - "runtime_env": { - "working_dir": "https://github.com/ray-project/serve_config_examples/archive/HEAD.zip" - }, - "deployments": [ - {"name": "MangoStand", "user_config": {"price": 1}}, - {"name": "OrangeStand", "user_config": {"price": 2}}, - {"name": "PearStand", "user_config": {"price": 3}} - ] -} -``` - -**Example Response** - - -```http -HTTP/1.1 200 OK -Content-Type: application/json -``` - -#### `GET "/api/serve/deployments/status"` - -Gets the Serve application's current status, including all the deployment statuses. This config represents the current goal state for the Serve application. Starts a Serve application on the Ray cluster if it's not already running. See the [status schema](serve-rest-api-status-schema) for the response's JSON schema. - -**Example Request**: - -``` -GET /api/serve/deployments/ HTTP 1.1 -Host: http://localhost:52365/ -Accept: application/json -``` - -**Example Response** - -```http -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "app_status": { - "status": "RUNNING", - "message": "", - "deployment_timestamp": 1855994527.146304 - }, - "deployment_statuses": [ - { - "name": "MangoStand", - "status": "HEALTHY", - "message": "" - }, - { - "name": "OrangeStand", - "status": "HEALTHY", - "message": "" - }, - { - "name": "PearStand", - "status": "HEALTHY", - "message": "" - }, - { - "name": "FruitMarket", - "status": "HEALTHY", - "message": "" - }, - { - "name": "DAGDriver", - "status": "HEALTHY", - "message": "" - } - ] -} -``` - -#### `DELETE "/api/serve/deployments/"` - -Shuts down the Serve application running on the Ray cluster. Has no -effect if Serve is not running on the Ray cluster. - -**Example Request**: - -``` -DELETE /api/serve/deployments/ HTTP 1.1 -Host: http://localhost:52365/ -Accept: application/json -``` - -**Example Response** - -```http -HTTP/1.1 200 OK -Content-Type: application/json -``` - -(serve-rest-api-config-schema)= - -### Config Schema - -```{eval-rst} -.. autopydantic_model:: ray.serve.schema.ServeApplicationSchema - -``` - -(serve-rest-api-status-schema)= - -### Status Schema - -```{eval-rst} -.. autopydantic_model:: ray.serve.schema.ServeStatusSchema - -``` - -(serve-cli)= - -## Serve CLI - -```{eval-rst} -.. click:: ray.serve.scripts:cli - :prog: serve - :show-nested: -``` +serve_cli +rest_api +``` \ No newline at end of file diff --git a/doc/source/serve/rest_api.md b/doc/source/serve/rest_api.md new file mode 100644 index 000000000..5e5f0b9fa --- /dev/null +++ b/doc/source/serve/rest_api.md @@ -0,0 +1,154 @@ +(serve-rest-api)= + +# Serve REST API + +## REST API + +``` +GET /api/serve/deployments/ HTTP 1.1 +Host: http://localhost:52365/ +Accept: application/json +``` + +**Example Response**: + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "import_path": "fruit.deployment_graph", + "runtime_env": { + "working_dir": "https://github.com/ray-project/serve_config_examples/archive/HEAD.zip" + }, + "deployments": [ + {"name": "MangoStand", "user_config": {"price": 1}}, + {"name": "OrangeStand", "user_config": {"price": 2}}, + {"name": "PearStand", "user_config": {"price": 3}} + ] +} +``` + +### `PUT "/api/serve/deployments/"` + +Declaratively deploys the Serve application. Starts Serve on the Ray cluster if it's not already running. See the [config schema](serve-rest-api-config-schema) for the request's JSON schema. + +**Example Request**: + +``` +PUT /api/serve/deployments/ HTTP 1.1 +Host: http://localhost:52365/ +Accept: application/json + +{ + "import_path": "fruit.deployment_graph", + "runtime_env": { + "working_dir": "https://github.com/ray-project/serve_config_examples/archive/HEAD.zip" + }, + "deployments": [ + {"name": "MangoStand", "user_config": {"price": 1}}, + {"name": "OrangeStand", "user_config": {"price": 2}}, + {"name": "PearStand", "user_config": {"price": 3}} + ] +} +``` + +**Example Response** + + +```http +HTTP/1.1 200 OK +Content-Type: application/json +``` + +### `GET "/api/serve/deployments/status"` + +Gets the Serve application's current status, including all the deployment statuses. This config represents the current goal state for the Serve application. Starts a Serve application on the Ray cluster if it's not already running. See the [status schema](serve-rest-api-status-schema) for the response's JSON schema. + +**Example Request**: + +``` +GET /api/serve/deployments/ HTTP 1.1 +Host: http://localhost:52365/ +Accept: application/json +``` + +**Example Response** + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "app_status": { + "status": "RUNNING", + "message": "", + "deployment_timestamp": 1855994527.146304 + }, + "deployment_statuses": [ + { + "name": "MangoStand", + "status": "HEALTHY", + "message": "" + }, + { + "name": "OrangeStand", + "status": "HEALTHY", + "message": "" + }, + { + "name": "PearStand", + "status": "HEALTHY", + "message": "" + }, + { + "name": "FruitMarket", + "status": "HEALTHY", + "message": "" + }, + { + "name": "DAGDriver", + "status": "HEALTHY", + "message": "" + } + ] +} +``` + +### `DELETE "/api/serve/deployments/"` + +Shuts down the Serve application running on the Ray cluster. Has no +effect if Serve is not running on the Ray cluster. + +**Example Request**: + +``` +DELETE /api/serve/deployments/ HTTP 1.1 +Host: http://localhost:52365/ +Accept: application/json +``` + +**Example Response** + +```http +HTTP/1.1 200 OK +Content-Type: application/json +``` + +(serve-rest-api-config-schema)= + +## Config Schema + +```{eval-rst} +.. autopydantic_model:: ray.serve.schema.ServeApplicationSchema + +``` + +(serve-rest-api-status-schema)= + +## Status Schema + +```{eval-rst} +.. autopydantic_model:: ray.serve.schema.ServeStatusSchema + +``` \ No newline at end of file diff --git a/doc/source/serve/serve_cli.md b/doc/source/serve/serve_cli.md new file mode 100644 index 000000000..7f3f2705c --- /dev/null +++ b/doc/source/serve/serve_cli.md @@ -0,0 +1,9 @@ +(serve-cli)= + +# Serve CLI + +```{eval-rst} +.. click:: ray.serve.scripts:cli + :prog: serve + :show-nested: +``` \ No newline at end of file