[DOC] Add docs about pagination abilities

Pagination abilities are described in
doc/source/restapi.rst file and in api-ref

Change-Id: Ia653f1fb22a640299a1d2642ea11d9b0215dc000
bp: pagination

api-ref/source/cluster-templates.inc

@@ -157,13 +157,18 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
-
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_cluster_templates
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
+   - markers: markers
+   - prev: prev
+   - next: next
    - description: description
    - use_autoconfig: use_autoconfig
    - cluster_configs: cluster_configs
@@ -185,6 +190,7 @@ Response Parameters
 
 Response Example
 ----------------
+.. rest_method:: GET /v1.1/{tenant_id}/cluster-templates?limit=2
 
 .. literalinclude:: samples/cluster-templates/cluster-templates-list-response.json
    :language: javascript

api-ref/source/clusters.inc

@@ -25,6 +25,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_clusters
 
 
 
@@ -33,6 +36,9 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - markers: markers
+   - prev: prev
+   - next: next
    - count: count
    - info: info
    - cluster_template_id: cluster_template_id
@@ -49,6 +55,7 @@ Response Parameters
 
 Response Example
 ----------------
+.. rest_method:: GET /v1.1/{tenant_id}/clusters
 
 .. literalinclude:: samples/clusters/clusters-list-response.json
    :language: javascript

api-ref/source/data-sources.inc

@@ -130,6 +130,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_data_sources
 
 
 Response Parameters
@@ -137,6 +140,9 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - markers: markers
+   - prev: prev
+   - next: next
    - description: description
    - url: url
    - tenant_id: tenant_id
@@ -153,6 +159,8 @@ Response Parameters
 Response Example
 ----------------
 
+.. rest_method:: GET /v1.1/{tenant-id}/data-sourses?sort_by=-name
+
 .. literalinclude:: samples/data-sources/data-sources-list-response.json
    :language: javascript
 

api-ref/source/job-binaries.inc

@@ -27,6 +27,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_job_binary
 
 
 
@@ -35,6 +38,9 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - markers: markers
+   - prev: prev
+   - next: next
    - description: description
    - url: url
    - tenant_id: tenant_id
@@ -50,6 +56,7 @@ Response Parameters
 
 Response Example
 ----------------
+.. rest_method:: GET /v1.1/{tenant_id}/job-binaries?sort_by=created_at
 
 .. literalinclude:: samples/job-binaries/list-response.json
    :language: javascript

api-ref/source/job-binary-internals.inc

@@ -224,6 +224,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_job_binary_internals
 
 
 
@@ -232,6 +235,9 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - markers: markers
+   - prev: prev
+   - next: next
    - binaries: binaries
    - name: name
    - tenant_id: tenant_id
@@ -246,6 +252,7 @@ Response Parameters
 
 Response Example
 ----------------
+.. rest_method:: GET /v1.1/{tenant_id}/job-binary-internals
 
 .. literalinclude:: samples/job-binary-internals/list-response.json
    :language: javascript

api-ref/source/job-executions.inc

@@ -85,6 +85,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_job_execution
 
 
 
@@ -93,6 +96,9 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - markers: markers
+   - prev: prev
+   - next: next
    - info: info
    - output_id: output_id
    - start_time: start_time
@@ -119,6 +125,7 @@ Response Parameters
 
 Response Example
 ----------------
+.. rest_method:: /v1.1/{tenant_id}/job-executions
 
 .. literalinclude:: samples/job-executions/list-response.json
    :language: javascript

api-ref/source/jobs.inc

@@ -58,6 +58,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_jobs
 
 
 
@@ -79,11 +82,14 @@ Response Parameters
    - type: type
    - id: id
    - name: name
-
+   - markers: markers
+   - prev: prev
+   - next: next
 
 
 Response Example
 ----------------
+..rest_method:: GET /v1.1/{tenant_id}/jobs?limit=2
 
 .. literalinclude:: samples/jobs/jobs-list-response.json
    :language: javascript

api-ref/source/node-group-templates.inc

@@ -31,6 +31,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: url_tenant_id
+   - limit: limit
+   - marker: marker
+   - sort_by: sort_by_node_groups
 
 
 
@@ -39,6 +42,9 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - markers: markers
+   - prev: prev
+   - next: next
    - volume_local_to_instance: volume_local_to_instance
    - availability_zone: availability_zone
    - updated_at: updated_at
@@ -72,6 +78,7 @@ Response Parameters
 
 Response Example
 ----------------
+.. rest_method:: GET /v1.1/{tenant_id}/node-group-templates?limit=2&marker=38b4e146-1d39-4822-bad2-fef1bf304a52&sort_by=name
 
 .. literalinclude:: samples/node-group-templates/node-group-templates-list-response.json
    :language: javascript

api-ref/source/parameters.yaml

@@ -104,7 +104,117 @@ version_1:
   required: false
   type: string
 
+
 # variables in query
+limit:
+  description: |
+    Maximum number of objects in response data.
+  in: path
+  requred: false
+  type: integer
+
+marker:
+  description: |
+    ID of the last element on the list which
+    won't be in response.
+  in: path
+  required: false
+  type: string
+
+sort_by_cluster_templates:
+  description: |
+    The field for sorting cluster templates.
+    this parameter accepts the following values:
+    ``name``, ``plugin_name``, ``hadoop_version``,
+    ``created_at``, ``updated_at``, ``id``. Also
+    this values can started with ``-`` prefix for
+    descending sort. For example: ``-name``.
+  in: path
+  requred: false
+  type: string
+
+sort_by_clusters:
+  description: |
+    The field for sorting clusters.
+    this parameter accepts the following values:
+    ``name``, ``plugin_name``, ``hadoop_version``,
+    ``status``, ``id``. Also this values can
+    started with ``-`` prefix for descending sort.
+    For example: ``-name``.
+  in: path
+  required: false
+  type: string
+
+sort_by_data_sources:
+    description: |
+      The field for sorting data sources.
+      this parameter accepts the following values:
+      ``id``, ``name``, ``type``, ``created_at``,
+      ``updated_at``. Also this values can started
+      with ``-`` prefix for descending sort.
+      For example: ``-name``.
+    in: path
+    requred: false
+    type: string
+
+sort_by_job_binaries:
+  description: |
+    The field for sorting job binaries.
+    this parameter accepts the following values:
+    ``id``, ``name``, ``created_at``, ``updated_at``.
+    Also this values can started with ``-`` prefix
+    for descending sort. For example: ``-name``.
+  in: path
+  requred: false
+  type: string
+
+sort_by_job_binary_internals:
+    description: |
+      The field for sorting job binary internals.
+      this parameter accepts the following values:
+      ``id``, ``name``, ``created_at``, ``updated_at``.
+      Also this values can started with ``-`` prefix
+      for descending sort. For example: ``-name``.
+    in: path
+    requred: false
+    type: string
+
+sort_by_job_executions:
+    description: |
+      The field for sorting job executions.
+      this parameter accepts the following values:
+      ``id``, ``job_template``, ``cluster``,
+      ``status``. Also this values can started
+      with ``-`` prefix for descending sort.
+      For example: ``-cluster``.
+    in: path
+    required: false
+    type: string
+
+sort_by_jobs:
+    description: |
+      The field for sorting jobs.
+      this parameter accepts the following values:
+      ``id``, ``name``, ``type``, ``created_at``,
+      ``updated_at``. Also this values can started
+      with ``-`` prefix for descending sort.
+      For example: ``-name``.
+    in: path
+    required: false
+    type: string
+
+sort_by_node_group_templates:
+  description: |
+    The field for sorting node group templates.
+    this parameter accepts the following values:
+    ``name``, ``plugin_name``, ``hadoop_version``,
+    ``created_at``, ``updated_at``, ``id``. Also
+    this values can started with ``-`` prefix for
+    descending sort. For example: ``-name``.
+  in: path
+  requred: false
+  type: string
+
 url_tenant_id:
   description: |
     UUID of the tenant.
@@ -112,6 +222,7 @@ url_tenant_id:
   required: true
   type: string
 
+
 # variables in body
 args:
   description: |
@@ -571,6 +682,14 @@ mains:
   in: body
   required: true
   type: array
+markers:
+  description: |
+    The markers of previous and following pages of data.
+    This field exists only if ``limit`` is passed to
+    request.
+  in: body
+  required: false
+  type: object
 management_public_key:
   description: |
     The SSH key for the management network.
@@ -633,6 +752,12 @@ neutron_management_network:
   in: body
   required: true
   type: string
+next:
+  description: |
+    The marker of next page of list data.
+  in: body
+  required: false
+  type: string
 node_configs:
   description: |
     A set of key and value pairs that contain the
@@ -683,6 +808,13 @@ plugins:
   in: body
   required: true
   type: array
+prev:
+  description: |
+    The marker of previous page. May be ``null`` if
+    previous page is first or if current page is first.
+  in: body
+  required: false
+  type: string
 progress:
   description: |
     A progress indicator, as a percentage value, for

api-ref/source/samples/cluster-templates/cluster-templates-list-response.json

@@ -130,5 +130,9 @@
             "description": "",
             "is_protected": false
         }
-    ]
+    ],
+    "markers": {
+        "prev": null,
+        "next": "2c76e0d3-56cd-4d28-bb4f-4808e538c7b9"
+    }
 }

api-ref/source/samples/jobs/jobs-list-response.json

@@ -58,5 +58,9 @@
             ],
             "is_protected": false
         }
-    ]
+    ],
+    "markers": {
+        "prev": null,
+        "next": "c53832da-6e7b-449e-a166-9f9ce1718d03"
+    }
 }

api-ref/source/samples/node-group-templates/node-group-templates-list-response.json

@@ -68,5 +68,9 @@
             "security_groups": null,
             "volume_type": null
         }
-    ]
+    ],
+    "markers": {
+        "prev":"39dfc852-8588-4b61-8d2b-eb08a67ab240",
+        "next":"eaa0bd97-ab54-43df-83ab-77a9774d7358"
+    }
 }

doc/source/restapi.rst

@@ -48,9 +48,44 @@ or
     GET /v1.1/{tenant_id}/clusters
     Accept: application/json
 
-1.3 Faults
+1.3 Navigation by response
-----------
+--------------------------
+Sahara API supports delivering response data by pages. User can pass
+two parameters in API GET requests which return an array of objects.
+The parameters are:
 
+``limit`` - maximum number of objects in response data.
+This parameter must be a positive integer number.
+
+``marker`` - ID of the last element on the list which won't be in response.
+
+Example:
+Get 15 clusters after cluster with id=d62ad147-5c10-418c-a21a-3a6597044f29:
+
+.. soursecode:: http
+
+    GET /v1.1/{tenant_id}/clusters?limit=15&marker=d62ad147-5c10-418c-a21a-3a6597044f29
+
+For convenience, response contains markers of previous and following pages
+which are named 'prev' and 'next' fields. Also there is ``sort_by`` parameter
+for sorting objects. Sahara API supports ascending and descending sorting.
+
+Examples:
+Sort clusters by name:
+
+.. soursecode:: http
+
+    GET /v1.1/{tenant_id}/clusters?sort_by=name
+
+Sort clusters by date of creation in descending order:
+
+.. soursecode:: http
+
+    GET /v1.1/{tenant_id}/clusters?sort_by=-created_at
+
+
+1.4 Faults
+----------
 The sahara API returns an error response if a failure occurs while
 processing a request. Sahara uses only standard HTTP error codes. 4xx errors
 indicate problems in the particular request being sent from the client and