openstack/deb-sahara
Code Issues Proposed changes

[DOC] Add docs about pagination abilities

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

Change-Id: Ia653f1fb22a640299a1d2642ea11d9b0215dc000
bp: pagination
This commit is contained in:
Mikhail Lelyakin 2016-08-25 11:48:02 +03:00 committed by Mikhail
parent 4427f7698c
commit f41bb7dd26
13 changed files with 241 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
api-ref/source/cluster-templates.inc
View File

@ -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

7
api-ref/source/clusters.inc
View File

@ -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

8
api-ref/source/data-sources.inc
View File

@ -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

7
api-ref/source/job-binaries.inc
View File

@ -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

7
api-ref/source/job-binary-internals.inc
View File

@ -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

7
api-ref/source/job-executions.inc
View File

@ -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

8
api-ref/source/jobs.inc
View File

@ -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

7
api-ref/source/node-group-templates.inc
View File

@ -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

132
api-ref/source/parameters.yaml
View File

@ -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

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

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

6
api-ref/source/samples/jobs/jobs-list-response.json
View File

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

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

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

39
doc/source/restapi.rst
View File

@ -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