AMBARI-2126 - Update API docs with resource property information

git-svn-id: https://svn.apache.org/repos/asf/incubator/ambari/trunk@1482489 13f79535-47bb-0310-9956-ffa450edef68

ambari-server/docs/api/v1/cluster-resources.md

@@ -18,7 +18,35 @@ limitations under the License.
 # Cluster Resources
 Cluster resources represent named Hadoop clusters.  Clusters are top level resources.
 
+###API Summary
+
 - [List clusters](clusters.md)
 - [View cluster information](clusters-cluster.md)
 - [Create cluster](create-cluster.md)
 - [Delete cluster](delete-cluster.md)
+
+###Properties
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>Clusters/cluster_id</td>
+    <td>The unique cluster id</td>  
+  </tr>
+  <tr>
+    <td>Clusters/cluster_name</td>
+    <td>The cluster name</td>  
+  </tr>
+  <tr>
+    <td>Clusters/version</td>
+    <td>The HDP stack version</td>  
+  </tr>
+  <tr>
+    <td>Clusters/desired_configs</td>
+    <td>The desired configurations</td>  
+  </tr>
+</table>
+

ambari-server/docs/api/v1/clusters-cluster.md

@@ -1,4 +1,4 @@
-	<!---
+<!---
 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.
@@ -20,12 +20,50 @@ View Cluster Information
 
 [Back to Resources](index.md#resources)
 
+**Summary**
+
 Returns information for the specified cluster identified by ":name"
 
     GET /clusters/:name
 
 **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 information for the cluster "c1".
 
+    GET /clusters/c1
+    
     200 OK
     {
     	"href" : "http://your.ambari.server/api/v1/clusters/c1",

ambari-server/docs/api/v1/clusters.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,12 +20,51 @@ List Clusters
 
 [Back to Resources](index.md#resources)
 
+**Summary**
+
 Returns a collection of the currently configured clusters.
 
     GET /clusters
 
 **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 all currently configured clusters.
+
+    GET /clusters
+
     200 OK
     {
       "href" : "http://your.ambari.server/api/v1/clusters",
@@ -37,6 +75,6 @@ Returns a collection of the currently configured clusters.
           			"cluster_name" : "c1",
           			"version" : "HDP-1.2.0"
         		}
-      		} 	
+      		} 	      		
     	]
 	}

ambari-server/docs/api/v1/component-resources.md

@@ -17,10 +17,41 @@ limitations under the License.
 
 # Component Resources
 Component resources are the individual components of a service (e.g. HDFS/NameNode and MapReduce/JobTracker).  Components are sub-resources of services.
- 
+
+###API Summary 
 
 - [List service components](components.md)
 - [View component information](components-component.md)
 - [Create component](create-component.md)
 
 
+
+###Properties
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>ServiceComponentInfo/service_name</td>
+    <td>The name of the parent service</td>  
+  </tr>
+  <tr>
+    <td>ServiceComponentInfo/component_name</td>
+    <td>The component name</td>  
+  </tr>
+  <tr>
+    <td>ServiceComponentInfo/cluster_name</td>
+    <td>The name of the parent cluster</td>  
+  </tr>
+  <tr>
+    <td>ServiceComponentInfo/description</td>
+    <td>The component description</td>  
+  </tr>
+  <tr>
+    <td>ServiceComponentInfo/desired_configs</td>
+    <td>The desired configurations</td>  
+  </tr>
+</table>
+

ambari-server/docs/api/v1/components-component.md

@@ -20,12 +20,52 @@ View Component Information
 
 [Back to Resources](index.md#resources)
 
-Refers to a specific component identified by ":componentName" for a given service.
+**Summary**
+
+Return the component identified by ":componentName" for for the service identifired by ":serviceName".
 
     GET /clusters/:name/services/:serviceName/components/:componentName
 
 **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 /clusters/c1/services/HDFS/components/DATANODE
+
     200 OK
     {
     	"href" : "http://your.ambari.server/api/v1/clusters/c1/services/HDFS/components/DATANODE",

ambari-server/docs/api/v1/components.md

@@ -20,12 +20,54 @@ View Service Components
 
 [Back to Resources](index.md#resources)
 
-Refers to a collection of all components for a given service.
+**Summary**
 
-    GET /clusters/:name/services/:serviceName/components
+Returns a collection of all components for the service identified by ":serviceName" and the cluster identified by ":clusterName".
+
+    GET /clusters/:clusterName/services/:serviceName/components
 
 **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**
+
+Returns a collection of all components for the HDFS service of the cluster "c1".
+
+
+    GET /clusters/c1/services/HDFS/components
+
     200 OK
     {
     	"href" : "http://your.ambari.server/api/v1/clusters/c1/services/HDFS/components",

ambari-server/docs/api/v1/create-cluster.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,12 +20,51 @@ Create Cluster
 
 [Back to Resources](index.md#resources)
 
-Create a cluster named ‘c1’ with the property ‘Clusters/version’ = ‘HDP-1.2.0’.
 
+**Summary**
 
-    POST /clusters/c1
+Create a cluster identified by ":name".
+
+    POST /clusters/:name
+
+**Response**
 
-**Body**
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>201</td>
+    <td>Created</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+**Example**
+
+Create a cluster named ‘c1’ with the property ‘Clusters/version’ = ‘HDP-1.2.0’.
+
+    POST /clusters/c1
 
     {
       "Clusters": {
@@ -34,7 +72,6 @@ Create a cluster named ‘c1’ with the property ‘Clusters/version’ = ‘HD
       }
     }
 
-**Response**
 
-    200 OK
+    201 Created
     

ambari-server/docs/api/v1/create-component.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,13 +20,54 @@ Create Component
 
 [Back to Resources](index.md#resources)
 
-Create the NAMENODE component.
+**Summary**
 
+Create the component identified by ":componentName" for for the service identifired by ":serviceName" and the cluster identified by ":clusterName".
 
-    POST /clusters/c1/services/HDFS/components/NAMENODE
+    POST /clusters/:clusterName/services/:serviceName/components/:componentName
+    
+    
 
 
 **Response**
 
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>201</td>
+    <td>Created</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+**Example**
+
+Create the NAMENODE component of the HDFS service
+
+    POST /clusters/c1/services/HDFS/components/NAMENODE
+
     200 OK
     

ambari-server/docs/api/v1/create-host.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,13 +20,52 @@ Create Host
 
 [Back to Resources](index.md#resources)
 
-Create the host named your.ambari.host.
-
 
-    POST /clusters/c1/hosts/your.ambari.host
+**Summary**
 
+Create a host resource identified by ":hostName" in the cluster identified by ":clusterName".
 
+    POST /clusters/:clusterName/hosts/:hostName
+    
 **Response**
 
-    200 OK
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>201</td>
+    <td>Created</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+**Example**
+    
+Create the host named 'host1' in cluster 'c1'.
+    
+    POST /clusters/c1/hosts/host1
+
+    201 Created
     

ambari-server/docs/api/v1/create-hostcomponent.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,13 +20,55 @@ Create Host Component
 
 [Back to Resources](index.md#resources)
 
-Create the NAMENODE host component on your.ambari.host.
 
+**Summary**
+
+Create the host component named ":componentName" on the host named ":hostName".
 
-    POST clusters/c1/hosts/your.ambari.host/host_components/NAMENODE
+
+    POST clusters/:clusterName/hosts/:hostName/host_components/:componentName
 
 
 **Response**
 
-    200 OK
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>201</td>
+    <td>Created</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+**Example**
+
+Create the NAMENODE host component on the host named "h1".
+
+
+    POST clusters/c1/hosts/h1/host_components/NAMENODE
+ 
+    201 Created
     

ambari-server/docs/api/v1/create-service.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,13 +20,54 @@ Create Service
 
 [Back to Resources](index.md#resources)
 
-Create the HDFS service.
+**Summary**
 
+Create the service identified by ":serviceName" in the cluster identified by ":clusterName".
 
-    POST /clusters/c1/services/HDFS
+
+    POST /clusters/:clusterName/services/:serviceName
 
 
 **Response**
 
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>201</td>
+    <td>Created</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+**Example**
+
+Create the HDFS service.
+
+
+    POST /clusters/c1/services/HDFS
+
     200 OK
     

ambari-server/docs/api/v1/delete-cluster.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,13 +20,53 @@ Delete Cluster
 
 [Back to Resources](index.md#resources)
 
-Delete a cluster named ‘c1’.
-
+**Summary**
 
-    DELETE /clusters/c1
+Delete the cluster identified by ":name".
 
 
+    DELETE /clusters/:name
+    
 **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**
+
+Delete the cluster named ‘c1’.
+
+
+    DELETE /clusters/c1
+
     200 OK
     

ambari-server/docs/api/v1/host-component-resources.md

@@ -16,6 +16,57 @@ limitations under the License.
 -->
 
 # Host Component Resources
+###API Summary
+
+
+- [List host components](host-components.md)
+- [View host component information](host-component.md)
+- [Create host component](create-hostcomponent.md)
+- [Update host component](update-hostcomponent.md)
+
+###Properties
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>HostRoles/role_id</td>
+    <td>The host component id</td>  
+  </tr>
+  <tr>
+    <td>HostRoles/cluster_name</td>
+    <td>The name of the parent cluster</td>  
+  </tr>
+  <tr>
+    <td>HostRoles/host_name</td>
+    <td>The name of the parent host</td>  
+  </tr>
+  <tr>
+    <td>HostRoles/component_name</td>
+    <td>The name of the parenbt component</td>  
+  </tr>
+  <tr>
+    <td>HostRoles/state</td>
+    <td>The state of the host component</td>  
+  </tr>
+  <tr>
+    <td>HostRoles/actual_configs</td>
+    <td>The actual configuration</td>  
+  </tr>
+  <tr>
+    <td>HostRoles/desired_configs</td>
+    <td>The desired configuration</td>  
+  </tr>
+  <tr>
+    <td>HostRoles/stack_id</td>
+    <td>The stack id (e.g. HDP-1.3.0)</td>  
+  </tr>
+</table>
+
+
+
 ###States
 
 The current state of a host component resource can be determined by looking at the ServiceComponentInfo/state property.
@@ -23,8 +74,6 @@ The current state of a host component resource can be determined by looking at t
 
     GET api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=ServiceComponentInfo/state
 
-**Response**
-
     200 OK
     {
       "href" : "http://your.ambari.server/api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=ServiceComponentInfo/state",
@@ -97,22 +146,15 @@ The following table lists the possible values of the service resource ServiceCom
   </tr>
 </table>
 
-###Starting
+
+###Starting a Host Component
 A component can be started through the API by setting its state to be STARTED (see [update host component](update-hostcomponent.md)).
 
-###Starting
+###Stopping a Host Component
 A component can be stopped through the API by setting its state to be INSTALLED (see [update host component](update-hostcomponent.md)).
 
 ###Maintenance
 
-The user can update the desired state of a component through the API to be MAINTENANCE (see [update host component](update-hostcomponent.md)).  When a host component is into maintenance state it is basically taken off line. This state can be used, for example, to move a component like NameNode.  The NameNode component can be put in MAINTENANCE mode and then a new NameNode can be created for the service. 
-
-
+The user can update the desired state of a host component through the API to be MAINTENANCE (see [update host component](update-hostcomponent.md)).  When a host component is into maintenance state it is basically taken off line. This state can be used, for example, to move a component like NameNode.  The NameNode component can be put in MAINTENANCE mode and then a new NameNode can be created for the service. 
 
-###Examples
 
-
-- [List host components](host-components.md)
-- [View host component information](host-component.md)
-- [Create host component](create-hostcomponent.md)
-- [Update host component](update-hostcomponent.md)

ambari-server/docs/api/v1/host-component.md

@@ -20,11 +20,51 @@ View Host Component Information
 
 [Back to Resources](index.md#resources)
 
+**Summary**
+
 Returns information for a specific role on the given host.
 
     GET /clusters/:name/hosts/:hostName/host_components/:componentName
 
 **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**
+
+
+Returns information for a the DATANODE role on the the host named "host1" on the cluster named "c1".
+
+    GET /clusters/c1/hosts/host1/host_components/DATANODE
 
     200 OK
     {

ambari-server/docs/api/v1/host-components.md

@@ -20,11 +20,51 @@ List Host Components
 
 [Back to Resources](index.md#resources)
 
+**Summary**
+
 Returns a collection of components running on a given host.
 
     GET /clusters/:name/hosts/:hostName/host_components
 
 **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**
+
+Returns a collection of components running on a the host named "h1" on the cluster named "c1".
+
+    GET /clusters/c1/hosts/h1/host_components
 
     200 OK
     {
@@ -54,4 +94,4 @@ Returns a collection of components running on a given host.
     		},
     		...
 		]
-	}
+	}

ambari-server/docs/api/v1/host-resources.md

@@ -17,7 +17,128 @@ limitations under the License.
 
 # Host Resources
  
+ 
+###API Summary 
 
 - [List hosts](hosts.md)
 - [View host information](hosts-host.md)
 - [Create host](create-host.md)
+
+###Properties
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>Hosts/host_name</td>
+    <td>The host name</td>  
+  </tr>
+  <tr>
+    <td>Hosts/cluster_name</td>
+    <td>The name of the parent cluster</td>  
+  </tr>
+  <tr>
+    <td>Hosts/ip</td>
+    <td>The host ip address</td>  
+  </tr>
+  <tr>
+    <td>Hosts/total_mem</td>
+    <td>The total memory available on the host</td>  
+  </tr>
+  <tr>
+    <td>Hosts/cpu_count</td>
+    <td>The cpu count of the host</td>  
+  </tr>
+  <tr>
+    <td>Hosts/os_arch</td>
+    <td>The OS architechture of the host (e.g. x86_64)</td>  
+  </tr>
+  <tr>
+    <td>Hosts/os_type</td>
+    <td>The OS type of the host (e.g. centos6)</td>  
+  </tr>
+  <tr>
+    <td>Hosts/rack_info</td>
+    <td>The rack info of the host</td>  
+  </tr>
+  <tr>
+    <td>Hosts/last_heartbeat_time</td>
+    <td>The time of the last heartbeat from the host in milliseconds since Unix epoch</td>  
+  </tr>
+  <tr>
+    <td>Hosts/last_agent_env</td>
+    <td>Environment information from the host</td>  
+  </tr>
+  <tr>
+    <td>Hosts/last_registration_time</td>
+    <td>The time of the last registration of the host in milliseconds since Unix epoc</td>  
+  </tr>
+  <tr>
+    <td>Hosts/disk_info</td>
+    <td>The host disk infromation</td>  
+  </tr>
+  <tr>
+    <td>Hosts/host_status</td>
+    <td>The host status (UNKNOWN, HEALTHY, UNHEALTHY)</td>  
+  </tr>
+  <tr>
+    <td>Hosts/public_host_name</td>
+    <td>The public host name.  Note that this property is typically populated during the creation of the host resource in a way that is particular to the environment.  If the public hostname can not be determined then it will be the same as the host_name property. </td>  
+  </tr>
+  <tr>
+    <td>Hosts/host_state</td>
+    <td>The host state</td>  
+  </tr>
+  <tr>
+    <td>Hosts/desired_configs</td>
+    <td>The desired configurations</td>  
+  </tr>
+</table>
+
+###States
+
+The current state of a host resource can be determined by looking at the Hosts/host_state property.
+
+
+    GET api/v1/clusters/c1/hosts/h1?fields=Hosts/host_state
+
+    200 OK
+    {
+      "href" : "your.ambari.server/api/v1/clusters/c1/hosts/h1?fields=Hosts/host_state",
+      "Hosts" : {
+        "cluster_name" : "c1",
+        "host_state" : "HEALTHY",
+        "host_name" : "h1"
+      } 
+    }
+
+The following table lists the possible values of the host resource Hosts/host_state.
+<table>
+  <tr>
+    <th>State</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>INIT</td>
+    <td>New host state.</td>  
+  </tr>
+  <tr>
+    <td>WAITING_FOR_HOST_STATUS_UPDATES</td>
+    <td>Registration request is received from the Host but the host has not responded to its status update check.</td>  
+  </tr>
+  <tr>
+    <td>HEALTHY</td>
+    <td>The server is receiving heartbeats regularly from the host and the state of the host is healthy.</td>  
+  </tr>
+  <tr>
+    <td>HEARTBEAT_LOST</td>
+    <td>The server has not received a heartbeat from the host in the configured heartbeat expiry window.</td>  
+  </tr>
+  <tr>
+    <td>UNHEALTHY</td>
+    <td>Host is in unhealthy state as reported either by the Host itself or via any other additional means ( monitoring layer ).</td>  
+  </tr>
+</table>
+

ambari-server/docs/api/v1/hosts-host.md

@@ -20,11 +20,48 @@ View Host Information
 
 [Back to Resources](index.md#resources)
 
-Returns information about a single host in a given cluster.
+**Summary**
 
-    GET /clusters/:name/hosts/:hostName
+Returns information about a single host in the cluster identified by ":clusterName".
+
+    GET /clusters/:clusterName/hosts/:hostName
 
 **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**
+
+Returns information about the host name "host1" in the cluster named "c1".
 
     200 OK
     {

ambari-server/docs/api/v1/hosts.md

@@ -20,12 +20,52 @@ List Hosts
 
 [Back to Resources](index.md#resources)
 
-Returns a collection of all hosts in a given cluster.
+**Summary**
 
-    GET /clusters/:name/hosts
+Returns a collection of all hosts for the cluster identified by ":clusterName".
+
+    GET /clusters/:clusterName/hosts
 
 **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 hosts for the cluster named "c1".
 
+    GET /clusters/c1/hosts
+    
     200 OK
     {
     	"href" : "http://your.ambari.server/api/v1/clusters/c1/hosts/",

ambari-server/docs/api/v1/service-resources.md

@@ -18,6 +18,41 @@ limitations under the License.
 # Service Resources
 Service resources are services of a Hadoop cluster (e.g. HDFS, MapReduce and Ganglia).  Service resources are sub-resources of clusters. 
 
+###API Summary
+
+- [List services](services.md)
+- [View service information](services-service.md)
+- [Create service](create-service.md)
+- [Update services](update-services.md)
+- [Update service](update-service.md)
+
+###Properties
+
+<table>
+  <tr>
+    <th>Property</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>ServiceInfo/service_name</td>
+    <td>The service name</td>  
+  </tr>
+  <tr>
+    <td>ServiceInfo/cluster_name</td>
+    <td>The parent cluster name</td>  
+  </tr>
+  <tr>
+    <td>ServiceInfo/state</td>
+    <td>The current state of the service</td>  
+  </tr>
+  <tr>
+    <td>ServiceInfo/desired_configs</td>
+    <td>The desired configurations</td>  
+  </tr>
+</table>
+
+
+
 ###States
 
 The current state of a service resource can be determined by looking at the ServiceInfo/state property.
@@ -25,8 +60,6 @@ The current state of a service resource can be determined by looking at the Serv
 
     GET api/v1/clusters/c1/services/HDFS?fields=ServiceInfo/state
 
-**Response**
-
     200 OK
     {
       "href" : "http://your.ambari.server/api/v1/clusters/c1/services/HDFS?fields=ServiceInfo/state",
@@ -98,17 +131,11 @@ The following table lists the possible values of the service resource ServiceInf
   </tr>
 </table>
 
-###Starting
+###Starting a Service
 A service can be started through the API by setting its state to be STARTED (see [update service](update-service.md)).
 
-###Starting
+###Stopping a Service
 A service can be stopped through the API by setting its state to be INSTALLED (see [update service](update-service.md)).
 
-###Examples
 
-- [List services](services.md)
-- [View service information](services-service.md)
-- [Create service](create-service.md)
-- [Update services](update-services.md)
-- [Update service](update-service.md)
 

ambari-server/docs/api/v1/services-service.md

@@ -20,11 +20,49 @@ View Service Information
 
 [Back to Resources](index.md#resources)
 
-Refers to a specific service identified by ":serviceName" for a given cluster.
+**Summary**
 
-    GET /clusters/:name/services/:serviceName
+Gets the service information for the service identified by ":serviceName" for cluster identified by ":clusterName".
+
+    GET /clusters/:clusterName/services/:serviceName
 
 **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 information for the "HDFS" service of the cluster named "c1".
+
+    GET /clusters/c1/services/HDFS
 
     200 OK
     {

ambari-server/docs/api/v1/services.md

@@ -20,11 +20,51 @@ List Services
 
 [Back to Resources](index.md#resources)
 
-Returns a collection of the services in a given cluster.
+**Summary**
+
+Returns a collection of the services for the cluster identified by ":name".
 
     GET /clusters/:name/services
 
 **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 services for the cluster named "c1".
+
+    GET /clusters/c1/services
 
     200 OK
     {
@@ -52,4 +92,4 @@ Returns a collection of the services in a given cluster.
         	  	}	
         	}
         ]
-    }    
+    }    

ambari-server/docs/api/v1/update-hostcomponent.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -18,10 +17,51 @@ limitations under the License.
 
 Update Host Component
 =====
-
 [Back to Resources](index.md#resources)
 
-###Start the NameNode Component
+**Summary**
+
+Update a host component for a given host and component.
+
+    PUT api/v1/clusters/:name/hosts/:hostName/host_components/:hostComponentName
+
+**Response**
+
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>200</td>
+    <td>OK</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+
+**Example 1**
+
 Start the NAMENODE component by updating its state to 'STARTED'.
 
 
@@ -34,8 +74,6 @@ Start the NAMENODE component by updating its state to 'STARTED'.
     }
 
 
-**Response**
-
     202 Accepted
     {
       "href" : "http://your.ambari.server:8080/api/v1/clusters/c1/requests/12",
@@ -45,7 +83,8 @@ Start the NAMENODE component by updating its state to 'STARTED'.
       }
     }
     
-###Stop the NameNode Component
+**Example 2 **
+
 Stop the NAMENODE component by updating its state to 'INSTALLED'.
 
 
@@ -58,8 +97,6 @@ Stop the NAMENODE component by updating its state to 'INSTALLED'.
     }
 
 
-**Response**
-
     202 Accepted
     {
       "href" : "http://your.ambari.server:8080/api/v1/clusters/c1/requests/13",
@@ -69,7 +106,8 @@ Stop the NAMENODE component by updating its state to 'INSTALLED'.
       }
     }
     
-###Set MAINTENANCE Mode    
+**Example 3 **
+
 Put the NAMENODE component into 'MAINTENANCE' mode.
 
 
@@ -82,8 +120,6 @@ Put the NAMENODE component into 'MAINTENANCE' mode.
     }
 
 
-**Response**
-
     202 Accepted
     {
       "href" : "http://your.ambari.server:8080/api/v1/clusters/c1/requests/14",

ambari-server/docs/api/v1/update-service.md

@@ -20,20 +20,24 @@ Update Service
 
 [Back to Resources](index.md#resources)
 
-###Start the HDFS Service
-Start the HDFS service (update the state of the HDFS service to be ‘STARTED’).
+**Summary**
 
 
     PUT /clusters/c1/services/HDFS/
 
 **Body**
 
+Start the HDFS service (update the state of the HDFS service to be ‘STARTED’).
+
+
+    PUT /clusters/c1/services/HDFS
     {
       "ServiceInfo": {
         "state" : "STARTED”
       }
     }
 
+Update the service identified by ":serviceName" of the cluster identified by ":clusterName".
 
 **Response**
 
@@ -46,13 +50,49 @@ Start the HDFS service (update the state of the HDFS service to be ‘STARTED’
       } 
     }
 
-###Stop the HDFS Service
+**Example 2**
+
 Stop the HDFS service (update the state of the HDFS service to be ‘INSTALLED’).
 
 
-    PUT /clusters/c1/services/HDFS/
+    PUT /clusters/:clusterName/services/:serviceName
 
-**Body**
+
+**Response**
+
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>200</td>
+    <td>OK</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
+
+
+**Example 1**
 
     {
       "ServiceInfo": {
@@ -60,12 +100,9 @@ Stop the HDFS service (update the state of the HDFS service to be ‘INSTALLED
       }
     }
 
-
-**Response**
-
     202 Accepted
     {
-      "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/3",
+      "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/4",
       "Requests" : {
         "id" : 4,
         "status" : "InProgress"

ambari-server/docs/api/v1/update-services.md

@@ -1,4 +1,3 @@
-
 <!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
@@ -21,12 +20,53 @@ Update Services
 
 [Back to Resources](index.md#resources)
 
-)Update the state ofall ‘INSTALLED’  servicse to be ‘STARTED’.
+**Summary**
 
+Update all services of the cluster identified by ":clusterName".
+
+
+    PUT/clusters/:clusterName/services
+
+**Response**
+
+<table>
+  <tr>
+    <th>HTTP CODE</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>200</td>
+    <td>OK</td>  
+  </tr>
+  <tr>
+    <td>202</td>
+    <td>Accepted</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>500</td>
+    <td>Internal Server Error</td>  
+  </tr>
+</table>
 
-    PUT/clusters/c1/services?ServiceInfo/state=INSTALLED/
 
-**Body**
+**Example**
+
+Update the state of all ‘INSTALLED’ services to be ‘STARTED’ for the cluster "c1".
+
+
+    PUT/clusters/c1/services?ServiceInfo/state=INSTALLED/
 
     {
       "ServiceInfo": {
@@ -35,8 +75,6 @@ Update Services
     }
 
 
-**Response**
-
     202 Accepted
     {
       "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/3",