diff --git a/api-ref/source/os-aggregates.inc b/api-ref/source/os-aggregates.inc
index 1a472287811f..793d28da38c5 100644
--- a/api-ref/source/os-aggregates.inc
+++ b/api-ref/source/os-aggregates.inc
@@ -1,5 +1,4 @@
 .. -*- rst -*-
-.. needs:example_verification
 .. needs:body_verification
 
 ================================
@@ -47,7 +46,8 @@ Create Aggregate
 
 .. rest_method:: POST /os-aggregates
 
-Creates an aggregate in an availability zone.
+Creates an aggregate. If specifying an option availability_zone, the aggregate is
+created as an availability zone and the availability zone is visible to normal users.
 
 Normal response codes: 200
 
@@ -131,6 +131,8 @@ Update Aggregate
 .. rest_method:: PUT /os-aggregates/{aggregate_id}
 
 Updates either or both the name and availability zone for an aggregate.
+If the aggregate to be updated has host that already in the given
+availablility zone, the request will fail with 400 error.
 
 Normal response codes: 200
 
@@ -194,6 +196,8 @@ Request
 Response
 --------
 
+There is no body content for the response of a successful POST action.
+
 Add Host
 ========
 
@@ -299,7 +303,7 @@ Create Or Update Aggregate Metadata
 
 Creates or replaces metadata for an aggregate.
 
-Specify the ``set_metadata`` action in the request body.
+Specify the ``set_metadata`` action and metadata info in the request body.
 
 Normal response codes: 200
 
diff --git a/doc/api_samples/os-aggregates/aggregates-list-get-resp.json b/doc/api_samples/os-aggregates/aggregates-list-get-resp.json
index f10de405fcbd..3887b096f87c 100644
--- a/doc/api_samples/os-aggregates/aggregates-list-get-resp.json
+++ b/doc/api_samples/os-aggregates/aggregates-list-get-resp.json
@@ -5,7 +5,7 @@
             "created_at": "2013-08-18T12:17:56.856455",
             "deleted": false,
             "deleted_at": null,
-            "hosts": [],
+            "hosts": ["21549b2f665945baaa7101926a00143c"],
             "id": 1,
             "metadata": {
                 "availability_zone": "nova"
diff --git a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-list-get-resp.json.tpl b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-list-get-resp.json.tpl
index 642653d1e6e5..3cfe0a5d81a7 100644
--- a/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-list-get-resp.json.tpl
+++ b/nova/tests/functional/api_sample_tests/api_samples/os-aggregates/aggregates-list-get-resp.json.tpl
@@ -5,7 +5,9 @@
             "created_at": "%(strtime)s",
             "deleted": false,
             "deleted_at": null,
-            "hosts": [],
+            "hosts": [
+                 "%(compute_host)s"
+            ],
             "id": 1,
             "metadata": {
                 "availability_zone": "nova"
diff --git a/nova/tests/functional/api_sample_tests/test_aggregates.py b/nova/tests/functional/api_sample_tests/test_aggregates.py
index 0e1e79f1a16f..3ea3e3d358a8 100644
--- a/nova/tests/functional/api_sample_tests/test_aggregates.py
+++ b/nova/tests/functional/api_sample_tests/test_aggregates.py
@@ -20,7 +20,7 @@ class AggregatesSampleJsonTest(api_sample_base.ApiSampleTestBaseV21):
     ADMIN_API = True
     sample_dir = "os-aggregates"
 
-    def test_aggregate_create(self):
+    def _test_aggregate_create(self):
         subs = {
             "aggregate_id": '(?P<id>\d+)'
         }
@@ -28,18 +28,31 @@ class AggregatesSampleJsonTest(api_sample_base.ApiSampleTestBaseV21):
         return self._verify_response('aggregate-post-resp',
                                      subs, response, 200)
 
+    def test_aggregate_create(self):
+        self._test_aggregate_create()
+
+    def _test_add_host(self, aggregate_id, host):
+        subs = {
+            "host_name": host
+        }
+        response = self._do_post('os-aggregates/%s/action' % aggregate_id,
+                                 'aggregate-add-host-post-req', subs)
+        self._verify_response('aggregates-add-host-post-resp', subs,
+                              response, 200)
+
     def test_list_aggregates(self):
-        self.test_aggregate_create()
+        aggregate_id = self._test_aggregate_create()
+        self._test_add_host(aggregate_id, self.compute.host)
         response = self._do_get('os-aggregates')
         self._verify_response('aggregates-list-get-resp', {}, response, 200)
 
     def test_aggregate_get(self):
-        agg_id = self.test_aggregate_create()
+        agg_id = self._test_aggregate_create()
         response = self._do_get('os-aggregates/%s' % agg_id)
         self._verify_response('aggregates-get-resp', {}, response, 200)
 
     def test_add_metadata(self):
-        agg_id = self.test_aggregate_create()
+        agg_id = self._test_aggregate_create()
         response = self._do_post('os-aggregates/%s/action' % agg_id,
                                  'aggregate-metadata-post-req',
                                  {'action': 'set_metadata'})
@@ -47,14 +60,8 @@ class AggregatesSampleJsonTest(api_sample_base.ApiSampleTestBaseV21):
                               response, 200)
 
     def test_add_host(self):
-        aggregate_id = self.test_aggregate_create()
-        subs = {
-            "host_name": self.compute.host,
-        }
-        response = self._do_post('os-aggregates/%s/action' % aggregate_id,
-                                 'aggregate-add-host-post-req', subs)
-        self._verify_response('aggregates-add-host-post-resp', subs,
-                              response, 200)
+        aggregate_id = self._test_aggregate_create()
+        self._test_add_host(aggregate_id, self.compute.host)
 
     def test_remove_host(self):
         self.test_add_host()
@@ -67,7 +74,7 @@ class AggregatesSampleJsonTest(api_sample_base.ApiSampleTestBaseV21):
                               subs, response, 200)
 
     def test_update_aggregate(self):
-        aggregate_id = self.test_aggregate_create()
+        aggregate_id = self._test_aggregate_create()
         response = self._do_put('os-aggregates/%s' % aggregate_id,
                                   'aggregate-update-post-req', {})
         self._verify_response('aggregate-update-post-resp',