[tune] Support RESTful API for the Web Server (ray-project#4080)

Change the client/server API to RESTful design. This includes resource modeling, model URI's, and correct HTTP methods.

doc/source/tune-usage.rst

@@ -457,29 +457,43 @@ be wrapped with ``tune.function``):
     )
 
 
-Client API
-----------
+Tune Client API
+---------------
 
-You can modify an ongoing experiment by adding or deleting trials using the Tune Client API. To do this, verify that you have the ``requests`` library installed:
+You can interact with an ongoing experiment with the Tune Client API. The Tune Client API is organized around REST, which includes resource-oriented URLs, accepts form-encoded requests, returns JSON-encoded responses, and uses standard HTTP protocol.
 
-.. code-block:: bash
-
-    $ pip install requests
-
-To use the Client API, you can start your experiment with ``with_server=True``:
+To allow Tune to receive and respond to your API calls, you have to start your experiment with ``with_server=True``:
 
 .. code-block:: python
 
     run_experiments({...}, with_server=True, server_port=4321)
 
-Then, on the client side, you can use the following class. The server address defaults to ``localhost:4321``. If on a cluster, you may want to forward this port (e.g. ``ssh -L <local_port>:localhost:<remote_port> <address>``) so that you can use the Client on your local machine.
+The easiest way to use the Tune Client API is with the built-in TuneClient. To use TuneClient, verify that you have the ``requests`` library installed:
+
+.. code-block:: bash
+
+    $ pip install requests
+
+Then, on the client side, you can use the following class. If on a cluster, you may want to forward this port (e.g. ``ssh -L <local_port>:localhost:<remote_port> <address>``) so that you can use the Client on your local machine.
 
 .. autoclass:: ray.tune.web_server.TuneClient
     :members:
 
-
 For an example notebook for using the Client API, see the `Client API Example <https://github.com/ray-project/ray/tree/master/python/ray/tune/TuneClient.ipynb>`__.
 
+The API also supports curl. Here are the examples for getting trials (``GET /trials/[:id]``):
+
+.. code-block:: bash
+
+    curl http://<address>:<port>/trials
+    curl http://<address>:<port>/trials/<trial_id>
+
+And stopping a trial (``PUT /trials/[:id]``):
+
+.. code-block:: bash
+
+    curl -X PUT http://<address>:<port>/trials/<trial_id>
+
 
 Further Questions or Issues?
 ----------------------------

python/ray/tune/TuneClient.ipynb

@@ -8,7 +8,7 @@
    "source": [
     "from ray.tune.web_server import TuneClient\n",
     "\n",
-    "manager = TuneClient(tune_address=\"localhost:4321\")\n",
+    "manager = TuneClient(tune_address=\"localhost\", port_forward=4321)\n",
     "\n",
     "x = manager.get_all_trials()\n",
     "\n",
@@ -19,7 +19,6 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true,
     "scrolled": false
    },
    "outputs": [],
@@ -31,9 +30,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "import yaml\n",
@@ -45,9 +42,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "name, spec = [x for x in d.items()][0]"
@@ -79,7 +74,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.2"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

python/ray/tune/error.py

@@ -6,8 +6,3 @@
 class TuneError(Exception):
     """General error class raised by ray.tune."""
     pass
-
-
-class TuneManagerError(TuneError):
-    """Error raised in operating the Tune Manager."""
-    pass

python/ray/tune/test/tune_server_test.py

@@ -4,6 +4,8 @@
 
 import unittest
 import socket
+import subprocess
+import json
 
 import ray
 from ray import tune
@@ -44,7 +46,7 @@ def basicSetup(self):
         trials = [Trial("__fake", **kwargs), Trial("__fake", **kwargs)]
         for t in trials:
             runner.add_trial(t)
-        client = TuneClient("localhost:{}".format(port))
+        client = TuneClient("localhost", port)
         return runner, client
 
     def tearDown(self):
@@ -126,6 +128,25 @@ def testStopTrial(self):
         self.assertEqual(
             len([t for t in all_trials if t["status"] == Trial.RUNNING]), 0)
 
+    def testCurlCommand(self):
+        """Check if Stop Trial works."""
+        runner, client = self.basicSetup()
+        for i in range(2):
+            runner.step()
+        stdout = subprocess.check_output(
+            'curl "http://{}:{}/trials"'.format(client.server_address,
+                                                client.server_port),
+            shell=True)
+        self.assertNotEqual(stdout, None)
+        curl_trials = json.loads(stdout.decode())["trials"]
+        client_trials = client.get_all_trials()["trials"]
+        for curl_trial, client_trial in zip(curl_trials, client_trials):
+            self.assertEqual(curl_trial.keys(), client_trial.keys())
+            self.assertEqual(curl_trial["id"], client_trial["id"])
+            self.assertEqual(curl_trial["trainable_name"],
+                             client_trial["trainable_name"])
+            self.assertEqual(curl_trial["status"], client_trial["status"])
+
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)