AMBARI-2090 - Add content to API docs.

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

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

@@ -16,8 +16,103 @@ limitations under the License.
 -->
 
 # Host Component Resources
- 
+###States
+
+The current state of a host component resource can be determined by looking at the ServiceComponentInfo/state property.
+
+
+    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",
+      "ServiceComponentInfo" : {
+        "cluster_name" : "c1",
+        "component_name" : "NAMENODE",
+        "state" : "INSTALLED",
+        "service_name" : "HDFS"
+      }
+    }
+
+The following table lists the possible values of the service resource ServiceComponentInfo/state property.
+<table>
+  <tr>
+    <th>State</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>INIT</td>
+    <td>The initial clean state after the component is first created.</td>  
+  </tr>
+  <tr>
+    <td>INSTALLING</td>
+    <td>In the process of installing the component.</td>  
+  </tr>
+  <tr>
+    <td>INSTALL_FAILED</td>
+    <td>The component install failed.</td>  
+  </tr>
+  <tr>
+    <td>INSTALLED</td>
+    <td>The component has been installed successfully but is not currently running.</td>  
+  </tr>
+  <tr>
+    <td>STARTING</td>
+    <td>In the process of starting the component.</td>  
+  </tr>
+  <tr>
+    <td>STARTED</td>
+    <td>The component has been installed and started.</td>  
+  </tr>
+  <tr>
+    <td>STOPPING</td>
+    <td>In the process of stopping the component.</td>  
+  </tr>
+
+  <tr>
+    <td>UNINSTALLING</td>
+    <td>In the process of uninstalling the component.</td>  
+  </tr>
+  <tr>
+    <td>UNINSTALLED</td>
+    <td>The component has been successfully uninstalled.</td>  
+  </tr>
+  <tr>
+    <td>WIPING_OUT</td>
+    <td>In the process of wiping out the installed component.</td>  
+  </tr>
+  <tr>
+    <td>UPGRADING</td>
+    <td>In the process of upgrading the component.</td>  
+  </tr>
+  <tr>
+    <td>MAINTENANCE</td>
+    <td>The component has been marked for maintenance.</td>  
+  </tr>
+  <tr>
+    <td>UNKNOWN</td>
+    <td>The component state can not be determined.</td>  
+  </tr>
+</table>
+
+###Starting
+A component can be started through the API by setting its state to be STARTED (see [update host component](update-hostcomponent.md)).
+
+###Starting
+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. 
+
+
+
+###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/service-resources.md

@@ -18,6 +18,94 @@ 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. 
 
+###States
+
+The current state of a service resource can be determined by looking at the ServiceInfo/state property.
+
+
+    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",
+      "ServiceInfo" : {
+        "cluster_name" : "c1",
+        "state" : "INSTALLED",
+        "service_name" : "HDFS"
+      }
+    }
+
+The following table lists the possible values of the service resource ServiceInfo/state property.
+<table>
+  <tr>
+    <th>State</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>INIT</td>
+    <td>The initial clean state after the service is first created.</td>  
+  </tr>
+  <tr>
+    <td>INSTALLING</td>
+    <td>In the process of installing the service.</td>  
+  </tr>
+  <tr>
+    <td>INSTALL_FAILED</td>
+    <td>The service install failed.</td>  
+  </tr>
+  <tr>
+    <td>INSTALLED</td>
+    <td>The service has been installed successfully but is not currently running.</td>  
+  </tr>
+  <tr>
+    <td>STARTING</td>
+    <td>In the process of starting the service.</td>  
+  </tr>
+  <tr>
+    <td>STARTED</td>
+    <td>The service has been installed and started.</td>  
+  </tr>
+  <tr>
+    <td>STOPPING</td>
+    <td>In the process of stopping the service.</td>  
+  </tr>
+
+  <tr>
+    <td>UNINSTALLING</td>
+    <td>In the process of uninstalling the service.</td>  
+  </tr>
+  <tr>
+    <td>UNINSTALLED</td>
+    <td>The service has been successfully uninstalled.</td>  
+  </tr>
+  <tr>
+    <td>WIPING_OUT</td>
+    <td>In the process of wiping out the installed service.</td>  
+  </tr>
+  <tr>
+    <td>UPGRADING</td>
+    <td>In the process of upgrading the service.</td>  
+  </tr>
+  <tr>
+    <td>MAINTENANCE</td>
+    <td>The service has been marked for maintenance.</td>  
+  </tr>
+  <tr>
+    <td>UNKNOWN</td>
+    <td>The service state can not be determined.</td>  
+  </tr>
+</table>
+
+###Starting
+A service can be started through the API by setting its state to be STARTED (see [update service](update-service.md)).
+
+###Starting
+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)

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

@@ -0,0 +1,94 @@
+
+<!---
+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.
+-->
+
+Update Host Component
+=====
+
+[Back to Resources](index.md#resources)
+
+###Start the NameNode Component
+Start the NAMENODE component by updating its state to 'STARTED'.
+
+
+    PUT api/v1/clusters/c1/hosts/hostname/host_components/NAMENODE
+    
+    {
+      "HostRoles":{
+        "state":"STARTED"
+      }
+    }
+
+
+**Response**
+
+    202 Accepted
+    {
+      "href" : "http://your.ambari.server:8080/api/v1/clusters/c1/requests/12",
+      "Requests" : {
+        "id" : 12,
+        "status" : "InProgress"
+      }
+    }
+    
+###Stop the NameNode Component
+Stop the NAMENODE component by updating its state to 'INSTALLED'.
+
+
+    PUT api/v1/clusters/c1/hosts/hostname/host_components/NAMENODE
+    
+    {
+      "HostRoles":{
+        "state":"INSTALLED"
+      }
+    }
+
+
+**Response**
+
+    202 Accepted
+    {
+      "href" : "http://your.ambari.server:8080/api/v1/clusters/c1/requests/13",
+      "Requests" : {
+        "id" : 13,
+        "status" : "InProgress"
+      }
+    }
+    
+###Set MAINTENANCE Mode    
+Put the NAMENODE component into 'MAINTENANCE' mode.
+
+
+    PUT api/v1/clusters/c1/hosts/hostname/host_components/NAMENODE
+    
+    {
+      "HostRoles":{
+        "state":"MAINTENANCE"
+      }
+    }
+
+
+**Response**
+
+    202 Accepted
+    {
+      "href" : "http://your.ambari.server:8080/api/v1/clusters/c1/requests/14",
+      "Requests" : {
+        "id" : 14,
+        "status" : "InProgress"
+      }
+    }    

ambari-server/docs/api/v1/update-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,6 +20,7 @@ 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’).
 
 
@@ -45,3 +45,29 @@ Start the HDFS service (update the state of the HDFS service to be ‘STARTED’
         "status" : "InProgress"
       } 
     }
+
+###Stop the HDFS Service
+Stop the HDFS service (update the state of the HDFS service to be ‘INSTALLED’).
+
+
+    PUT /clusters/c1/services/HDFS/
+
+**Body**
+
+    {
+      "ServiceInfo": {
+        "state" : "INSTALLED”
+      }
+    }
+
+
+**Response**
+
+    202 Accepted
+    {
+      "href" : "http://your.ambari.server/api/v1/clusters/c1/requests/3",
+      "Requests" : {
+        "id" : 4,
+        "status" : "InProgress"
+      } 
+    }