doc: introduces a REST use-cases section

We should list all REST API use-case that people is asking for, to
not get issue opened for new feature when it's already possible to get
the data.

It's not always clear what API call I need to do to get all informations
I need for a use-cases.

This change starts a new section and add one example.

Related gnocchixyz#465.

doc/source/rest.j2

@@ -852,6 +852,17 @@ Operations between metrics can also be done, such as:
 
 {{ scenarios['get-aggregates-between-metrics']['doc'] }}
 
+List the top N resources that consume the most CPU during the last hour
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following is configured so that `stop` - `start` = `granularity` will get
+only one point per instance.
+
+This will give all information needed to order by `cpu.util` timeseries which
+can be filtered down to N results.
+
+
+{{ scenarios['use-case1-top-cpuutil-per-instances']['doc'] }}
 
 Aggregation across metrics (deprecated)
 =======================================
@@ -945,7 +956,6 @@ reporting values such as the number of new |measures| to process for each
 
 {{ scenarios['get-status']['doc'] }}
 
-
 Timestamp format
 ================
 

doc/source/rest.yaml

@@ -7,6 +7,10 @@
       "name": "short",
       "back_window": 0,
       "definition": [
+        {
+          "granularity": "1h",
+          "timespan": "7 day"
+        },
         {
           "granularity": "1s",
           "timespan": "1 hour"
@@ -52,6 +56,10 @@
 
     {
       "definition": [
+        {
+          "granularity": "1h",
+          "timespan": "7 day"
+        },
         {
           "granularity": "1s",
           "timespan": "1 hour"
@@ -825,3 +833,17 @@
 
 - name: get-status
   request: GET /v1/status HTTP/1.1
+
+
+- name: use-case1-top-cpuutil-per-instances
+  request: |
+    POST /v1/aggregates?start=2014-10-06T14:00&stop=2014-10-06T15:00&groupby=original_resource_id&groupby=display_name&granularity=3600.0 HTTP/1.1
+    Content-Type: application/json
+
+    {
+      "resource_type": "instance",
+      "search": "server_group='my_autoscaling_group'",
+      "operations": "(metric cpu.util mean)"
+    }
+
+