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

@@ -931,6 +931,22 @@ reporting values such as the number of new |measures| to process for each
 
 {{ scenarios['get-status']['doc'] }}
 
+Use-cases examples
+==================
+
+1. I want the top N instances for project_id "BD3A1E52-1C62-44CB-BF04-660BD88CD74D" that consume the most cpu last hour.
+
+To do so, I will use the :ref:`Dynamic aggregates API <aggregates>`. I will use
+|start|, |stop|, |granularity| and |groupby| parameters. The entire query will
+looke like:
+
+{{ scenarios['use-case1-top-cpuutil-per-instances']['doc'] }}
+
+I have ensured that |stop| - |start| = |granularity| to get only one point per
+instances.
+
+This will give all informations we need to order by cpu.util timeseries and
+pick only the N we are interrested in.
 
 Timestamp format
 ================

doc/source/rest.yaml

@@ -825,3 +825,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": {"=": {"project_id", "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"}},
+      "operations": "(metric cpu.util mean)"
+    }
+
+