From 380e355fb199ac38b70aba08be8a552943e005c1 Mon Sep 17 00:00:00 2001
From: Mehdi Abaakouk <sileht@redhat.com>
Date: Wed, 8 Nov 2017 16:42:33 +0100
Subject: [PATCH] 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 #465.
---
 doc/source/rest.j2   | 12 +++++++++++-
 doc/source/rest.yaml | 22 ++++++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/doc/source/rest.j2 b/doc/source/rest.j2
index 512c25bae..ade8999dc 100644
--- a/doc/source/rest.j2
+++ b/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
 ================
 
diff --git a/doc/source/rest.yaml b/doc/source/rest.yaml
index 61ffc5576..f1e469c26 100644
--- a/doc/source/rest.yaml
+++ b/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)"
+    }
+
+