AMBARI-2485 - API: Document task resource status values

5 files changed, 375 insertions, 0 deletions

diff --git a/ambari-server/docs/api/v1/index.md b/ambari-server/docs/api/v1/index.md
index d843b703fa..de2de5818c 100644
--- a/ambari-server/docs/api/v1/index.md
+++ b/ambari-server/docs/api/v1/index.md
@@ -295,6 +295,15 @@ Configuration resources are sets of key/value pairs that configure the services
 
 [Configuration Resource Overview](configuration.md)
 
+#### requests
+Request resources are groups of tasks that were created to carry out an instruction.
+
+[Request Resources](request-resources.md)
+
+#### tasks
+Task resources are the individual tasks that make up a request resource.
+
+[Task Resources](task-resources.md)
 
 #### workflows
 Workflow resources are DAGs of MapReduce jobs in a Hadoop cluster.
diff --git a/ambari-server/docs/api/v1/request_resources.md b/ambari-server/docs/api/v1/request_resources.md
new file mode 100644
index 0000000000..0618214332
--- /dev/null
+++ b/ambari-server/docs/api/v1/request_resources.md
@@ -0,0 +1,45 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Request Resources
+ 
+ 
+###API Summary 
+
+- [List requests](requests.md)
+
+###Properties
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>Requests/id</td>
+    <td>The request id</td>  
+  </tr>
+  <tr>
+    <td>Requests/cluster_name</td>
+    <td>The name of the parent cluster</td>  
+  </tr>
+  <tr>
+    <td>Requests/request_context</td>
+    <td>The context</td>  
+  </tr>
+</table>
+
diff --git a/ambari-server/docs/api/v1/requests.md b/ambari-server/docs/api/v1/requests.md
new file mode 100644
index 0000000000..474ea856fd
--- /dev/null
+++ b/ambari-server/docs/api/v1/requests.md
@@ -0,0 +1,90 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+List Requests
+=====
+
+[Back to Resources](index.md#resources)
+
+**Summary**
+
+Returns a collection of all requests for the cluster identified by ":clusterName".
+
+    GET /clusters/:clusterName/requests
+
+**Response**
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>200</td>
+    <td>OK</td>  
+  </tr>
+  <tr>
+    <td>400</td>
+    <td>Bad Request</td>  
+  </tr>
+  <tr>
+    <td>401</td>
+    <td>Unauthorized</td>  
+  </tr>
+  <tr>
+    <td>403</td>
+    <td>Forbidden</td>  
+  </tr> 
+  <tr>
+    <td>404</td>
+    <td>Not Found</td>  
+  </tr>
+  <tr>
+    <td>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+
+**Example**
+
+Get the collection of the requests for the cluster named "c1".
+
+    GET /clusters/c1/requests?fields=Requests/request_context
+    
+    200 OK
+    {
+    	"href" : "http://your.ambari.server/api/v1/clusters/c1/requests?fields=Requests/request_context",
+        "items" : [
+          {
+            "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/1",
+            "Requests" : {
+              "cluster_name" : "c1",
+              "id" : 1,
+              "request_context" : "Install Services"
+            }
+          },
+          {
+            "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/2",
+            "Requests" : {
+              "cluster_name" : "c1",
+              "id" : 2,
+              "request_context" : "Start Services"
+            }
+          }
+        ]	
+    }  	
diff --git a/ambari-server/docs/api/v1/task_resources.md b/ambari-server/docs/api/v1/task_resources.md
new file mode 100644
index 0000000000..ef22cfbffd
--- /dev/null
+++ b/ambari-server/docs/api/v1/task_resources.md
@@ -0,0 +1,139 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Task Resources
+ 
+ 
+###API Summary 
+
+- [List tasks](tasks.md)
+
+###Properties
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>Tasks/id</td>
+    <td>The task id</td>  
+  </tr>
+  <tr>
+    <td>Tasks/request_id</td>
+    <td>The parent request id</td>  
+  </tr>
+  <tr>
+    <td>Tasks/cluster_name</td>
+    <td>The name of the parent cluster</td>  
+  </tr>
+  <tr>
+    <td>Tasks/attempt_cnt</td>
+    <td>The number of attempts at completing this task</td>  
+  </tr>
+  <tr>
+    <td>Tasks/command</td>
+    <td>The task command</td>  
+  </tr>
+  <tr>
+    <td>Tasks/exit_code</td>
+    <td>The exit code</td>  
+  </tr>
+  <tr>
+    <td>Tasks/host_name</td>
+    <td>The name of the host</td>  
+  </tr>
+  <tr>
+    <td>Tasks/role</td>
+    <td>The role</td>  
+  </tr>
+  <tr>
+    <td>Tasks/stage_id</td>
+    <td>The stage id</td>  
+  </tr>
+  <tr>
+    <td>Tasks/start_time</td>
+    <td>The task start time</td>  
+  </tr>
+  <tr>
+    <td>Tasks/status</td>
+    <td>The task status</td>  
+  </tr>
+  <tr>
+    <td>Tasks/stderr</td>
+    <td>The stderr from running the taks</td>  
+  </tr>
+  <tr>
+    <td>Tasks/stdout</td>
+    <td>The stdout from running the task</td>  
+  </tr>
+</table>
+
+
+###Status
+
+The current status of a task resource can be determined by looking at the Tasks/status property.
+
+
+    GET api/v1/clusters/c1/requests/2/tasks/12?fields=Tasks/status
+
+    200 OK
+    {
+      "href" : "your.ambari.server/api/v1/clusters/c1/requests/2/tasks/12?fields=Tasks/status",
+      "Tasks" : {
+      "cluster_name" : "c1",
+      "id" : 12,
+      "request_id" : 2,
+      "status" : "COMPLETED"
+    }
+
+The following table lists the possible values of the task resource Tasks/status.
+<table>
+  <tr>
+    <th>State</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>PENDING</td>
+    <td>Not queued for a host.</td>  
+  </tr>
+  <tr>
+    <td>QUEUED</td>
+    <td>Queued for a host.</td>  
+  </tr>
+  <tr>
+    <td>IN_PROGRESS</td>
+    <td>Host reported it is working.</td>  
+  </tr>
+  <tr>
+    <td>COMPLETED</td>
+    <td>Host reported success.</td>  
+  </tr>
+  <tr>
+    <td>FAILED</td>
+    <td>Failed.</td>  
+  </tr>
+  <tr>
+    <td>TIMEDOUT</td>
+    <td>Host did not respond in time.</td>  
+  </tr>
+  <tr>
+    <td>ABORTED</td>
+    <td>Operation was abandoned.</td>  
+  </tr>
+</table>
+
diff --git a/ambari-server/docs/api/v1/tasks.md b/ambari-server/docs/api/v1/tasks.md
new file mode 100644
index 0000000000..a06790f1d8
--- /dev/null
+++ b/ambari-server/docs/api/v1/tasks.md
@@ -0,0 +1,92 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+List Tasks
+=====
+
+[Back to Resources](index.md#resources)
+
+**Summary**
+
+Returns a collection of all tasks for the request identified by ":requestId" and the cluster identified by ":clusterName".
+
+    GET /clusters/:clusterName/requests/:requestId/tasks
+
+**Response**
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>200</td>
+    <td>OK</td>  
+  </tr>
+  <tr>
+    <td>400</td>
+    <td>Bad Request</td>  
+  </tr>
+  <tr>
+    <td>401</td>
+    <td>Unauthorized</td>  
+  </tr>
+  <tr>
+    <td>403</td>
+    <td>Forbidden</td>  
+  </tr> 
+  <tr>
+    <td>404</td>
+    <td>Not Found</td>  
+  </tr>
+  <tr>
+    <td>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+
+**Example**
+
+Get the collection of the tasks for the request 2 and the cluster named "c1".
+
+    GET /clusters/c1/requests/2/tasks?fields=Tasks/status
+    
+    200 OK
+    {
+        "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/2/tasks?fields=Tasks/status",
+        "items" : [
+          {
+            "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/2/tasks/12",
+            "Tasks" : {
+              "cluster_name" : "c1",
+              "id" : 12,
+              "request_id" : 2,
+              "status" : "COMPLETED"
+            }
+          },
+          {
+            "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/2/tasks/13",
+            "Tasks" : {
+              "cluster_name" : "c1",
+              "id" : 13,
+              "request_id" : 2,
+              "status" : "IN_PROGRESS"
+            }
+          }
+        ]	
+      }