From 97166ba58c4ac9c2f4ea52cb21210962f3e3727f Mon Sep 17 00:00:00 2001 From: Mark DeCrane Date: Tue, 29 Oct 2024 13:20:03 -0400 Subject: [PATCH 1/4] Document unique pagination method used in Org Runs Index endpoint --- website/docs/cloud-docs/api-docs/run.mdx | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index c434f2adf..cd5f9a13e 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -456,6 +456,8 @@ curl \ This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second. +Note that this endpoint differs from others in the pagination metadata included in the response, such as the exclusion of the typical `total-count`. See the Sample Response below for more details. + | Status | Response | Reason | |---------|--------------------------------------------------|--------------------------| | [200][] | Array of [JSON API document][]s (`type: "runs"`) | Successfully listed runs | @@ -553,7 +555,16 @@ curl \ } }, {...} - ] + ], + "meta": { + "pagination": { + "current-page": 1, + "next-page": 2, + "prev-page": null, + "page-size": 20, + "page-count": 20 + } + } } ``` From 8bae39635674cd3708f444a1530414da715e8870 Mon Sep 17 00:00:00 2001 From: Mark DeCrane Date: Tue, 29 Oct 2024 13:29:53 -0400 Subject: [PATCH 2/4] update api docs changelog --- website/docs/cloud-docs/api-docs/changelog.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/docs/cloud-docs/api-docs/changelog.mdx b/website/docs/cloud-docs/api-docs/changelog.mdx index baf21f492..434c37543 100644 --- a/website/docs/cloud-docs/api-docs/changelog.mdx +++ b/website/docs/cloud-docs/api-docs/changelog.mdx @@ -9,6 +9,8 @@ description: >- Keep track of changes to the API for HCP Terraform and Terraform Enterprise. +## 2024-10-15 +* Document unique pagination metadata given in the response of [Organization Runs Index API](/terraform/cloud-docs/api-docs/run##list-runs-in-an-organization). ## 2024-10-15 * Add new documentation for the ability to deprecate, and revert the deprecation of, module versions. Learn more about [Managing module versions](/terraform/cloud-docs/api-docs/private-registry/manage-module-versions). From c8c14f5ea0c3256c7e57053c1fc72a04997fe23a Mon Sep 17 00:00:00 2001 From: Mark DeCrane Date: Tue, 29 Oct 2024 16:56:04 -0400 Subject: [PATCH 3/4] More detailed list of excluded pagination attributes --- website/docs/cloud-docs/api-docs/run.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index cd5f9a13e..5872d24ef 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -456,7 +456,7 @@ curl \ This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second. -Note that this endpoint differs from others in the pagination metadata included in the response, such as the exclusion of the typical `total-count`. See the Sample Response below for more details. +Note that this endpoint differs from others in the pagination metadata included in the response, such as the exclusion of the typical `total-count` and `total-pages`. See the Sample Response below for more details. | Status | Response | Reason | |---------|--------------------------------------------------|--------------------------| From c8aefb11081b6dc2cbe5b3234ffe0418575e0e80 Mon Sep 17 00:00:00 2001 From: Mark DeCrane Date: Wed, 30 Oct 2024 12:19:42 -0400 Subject: [PATCH 4/4] Update org runs list docs to include pagination links, update workspace runs list docs to include pagination metadata --- website/docs/cloud-docs/api-docs/run.mdx | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/api-docs/run.mdx b/website/docs/cloud-docs/api-docs/run.mdx index 5872d24ef..3256d66a5 100644 --- a/website/docs/cloud-docs/api-docs/run.mdx +++ b/website/docs/cloud-docs/api-docs/run.mdx @@ -442,7 +442,24 @@ curl \ } }, {...} - ] + ], + "links": { + "first": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=1&page[size]=20", + "last": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=19206&page[size]=20", + "self": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=2&page[size]=20", + "prev": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=1&page[size]=20", + "next": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=3&page[size]=20" + }, + "meta": { + "pagination": { + "current-page": 2, + "next-page": 3, + "prev-page": 1, + "page-size": 20, + "total-count": 384105, + "total-pages": 19206 + } + } } ``` @@ -556,6 +573,11 @@ curl \ }, {...} ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=2&page[size]=20", + "prev": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=1&page[size]=20", + "next": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=3&page[size]=20" + }, "meta": { "pagination": { "current-page": 1,