From f41bb7dd268649cff6d257a121f204aabce025c5 Mon Sep 17 00:00:00 2001 From: Mikhail Lelyakin Date: Thu, 25 Aug 2016 11:48:02 +0300 Subject: [PATCH] [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 | 8 +- api-ref/source/clusters.inc | 7 + api-ref/source/data-sources.inc | 8 ++ api-ref/source/job-binaries.inc | 7 + api-ref/source/job-binary-internals.inc | 7 + api-ref/source/job-executions.inc | 7 + api-ref/source/jobs.inc | 8 +- api-ref/source/node-group-templates.inc | 7 + api-ref/source/parameters.yaml | 132 ++++++++++++++++++ .../cluster-templates-list-response.json | 6 +- .../samples/jobs/jobs-list-response.json | 6 +- .../node-group-templates-list-response.json | 6 +- doc/source/restapi.rst | 39 +++++- 13 files changed, 241 insertions(+), 7 deletions(-) diff --git a/api-ref/source/cluster-templates.inc b/api-ref/source/cluster-templates.inc index 12af57a7..9248719b 100644 --- a/api-ref/source/cluster-templates.inc +++ b/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 diff --git a/api-ref/source/clusters.inc b/api-ref/source/clusters.inc index 089ec5de..e4b436eb 100644 --- a/api-ref/source/clusters.inc +++ b/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 diff --git a/api-ref/source/data-sources.inc b/api-ref/source/data-sources.inc index af1c918e..676cbbbc 100644 --- a/api-ref/source/data-sources.inc +++ b/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 diff --git a/api-ref/source/job-binaries.inc b/api-ref/source/job-binaries.inc index 6786b4ec..2df5dcea 100644 --- a/api-ref/source/job-binaries.inc +++ b/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 diff --git a/api-ref/source/job-binary-internals.inc b/api-ref/source/job-binary-internals.inc index 2506eaae..f97b1ac1 100644 --- a/api-ref/source/job-binary-internals.inc +++ b/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 diff --git a/api-ref/source/job-executions.inc b/api-ref/source/job-executions.inc index f98b25d6..17ee3c61 100644 --- a/api-ref/source/job-executions.inc +++ b/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 diff --git a/api-ref/source/jobs.inc b/api-ref/source/jobs.inc index 82c2aad0..467e73c3 100644 --- a/api-ref/source/jobs.inc +++ b/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 diff --git a/api-ref/source/node-group-templates.inc b/api-ref/source/node-group-templates.inc index 7601972e..4d8373fc 100644 --- a/api-ref/source/node-group-templates.inc +++ b/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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index a95b5547..25eaec04 100644 --- a/api-ref/source/parameters.yaml +++ b/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 diff --git a/api-ref/source/samples/cluster-templates/cluster-templates-list-response.json b/api-ref/source/samples/cluster-templates/cluster-templates-list-response.json index 18f72587..2f83930b 100644 --- a/api-ref/source/samples/cluster-templates/cluster-templates-list-response.json +++ b/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" + } } diff --git a/api-ref/source/samples/jobs/jobs-list-response.json b/api-ref/source/samples/jobs/jobs-list-response.json index 7f0d04de..e19b3d59 100644 --- a/api-ref/source/samples/jobs/jobs-list-response.json +++ b/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" + } } diff --git a/api-ref/source/samples/node-group-templates/node-group-templates-list-response.json b/api-ref/source/samples/node-group-templates/node-group-templates-list-response.json index 37c296cd..c41683e9 100644 --- a/api-ref/source/samples/node-group-templates/node-group-templates-list-response.json +++ b/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" + } } diff --git a/doc/source/restapi.rst b/doc/source/restapi.rst index be044663..f42c952f 100644 --- a/doc/source/restapi.rst +++ b/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