From 2ba183ff20ffe3ba1bc0154024f7c288b17f7354 Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Tue, 17 Dec 2024 22:30:20 +0000 Subject: [PATCH] Add note to remind server users to update hostname in API examples (#9137) * add note for api examples for server readers * add note about using server hostname to all how-to guides that use the API * add more context to the note --- jekyll/_cci2/api-developers-guide.adoc | 2 ++ jekyll/_cci2/artifacts.adoc | 2 ++ jekyll/_cci2/configuration-reference.adoc | 2 ++ jekyll/_cci2/contexts.adoc | 2 ++ jekyll/_cci2/inject-environment-variables-with-api.adoc | 2 ++ jekyll/_cci2/pipeline-variables.adoc | 2 ++ jekyll/_cci2/workflows.adoc | 2 ++ jekyll/_includes/partials/notes/server-api-examples.adoc | 1 + 8 files changed, 15 insertions(+) create mode 100644 jekyll/_includes/partials/notes/server-api-examples.adoc diff --git a/jekyll/_cci2/api-developers-guide.adoc b/jekyll/_cci2/api-developers-guide.adoc index ef011742cd6..3fe99d24de6 100644 --- a/jekyll/_cci2/api-developers-guide.adoc +++ b/jekyll/_cci2/api-developers-guide.adoc @@ -13,6 +13,8 @@ contentTags: This guide was written to assist developers in making API calls to CircleCI services to return detailed information about users, pipelines, projects, and workflows. The API v2 Specification itself may be viewed in the https://circleci.com/docs/api/v2/[Reference documentation]. +include::../_includes/partials/notes/server-api-examples.adoc[] + [#api-categories] == API categories diff --git a/jekyll/_cci2/artifacts.adoc b/jekyll/_cci2/artifacts.adoc index dfdbb97d782..6674110beb3 100644 --- a/jekyll/_cci2/artifacts.adoc +++ b/jekyll/_cci2/artifacts.adoc @@ -140,6 +140,8 @@ When CircleCI runs a job, a link to the core dump file appears in the *Artifacts [#downloading-all-artifacts-for-a-build-on-circleci] == Downloading all artifacts for a build on CircleCI +include::../_includes/partials/notes/server-api-examples.adoc[] + To download your artifacts with `curl`, follow the steps below. . xref:managing-api-tokens#creating-a-personal-api-token[Create a personal API token] and copy it to a clipboard. diff --git a/jekyll/_cci2/configuration-reference.adoc b/jekyll/_cci2/configuration-reference.adoc index 9d68c3afcb6..b21fd6b3049 100644 --- a/jekyll/_cci2/configuration-reference.adoc +++ b/jekyll/_cci2/configuration-reference.adoc @@ -2861,6 +2861,8 @@ workflows: You can use the API to trigger a pipeline with a pipeline parameter set to true: +include::../_includes/partials/notes/server-api-examples.adoc[] + [source,yml] ---- curl -X POST https://circleci.com/api/v2/project/circleci///pipeline/run \ diff --git a/jekyll/_cci2/contexts.adoc b/jekyll/_cci2/contexts.adoc index c343baeb130..97da93c8ee2 100644 --- a/jekyll/_cci2/contexts.adoc +++ b/jekyll/_cci2/contexts.adoc @@ -278,6 +278,8 @@ Follow these steps to set an expression restriction on a context: [.tab.set-expression-restriction.API] -- +include::../_includes/partials/notes/server-api-examples.adoc[] + . Set up your API authentication. Steps are available in the xref:api-developers-guide#add-an-api-token[API developers guide]. . You are going to need your organization ID. In the link:https://app.circleci.com/[CircleCI web app] select **Organization Settings** in the sidebar and copy your "Organization ID" somewhere safe. . To get the ID for your context, list your contexts, as follows, substituting your organization ID: diff --git a/jekyll/_cci2/inject-environment-variables-with-api.adoc b/jekyll/_cci2/inject-environment-variables-with-api.adoc index c80975e082d..929dbd1d288 100644 --- a/jekyll/_cci2/inject-environment-variables-with-api.adoc +++ b/jekyll/_cci2/inject-environment-variables-with-api.adoc @@ -11,6 +11,8 @@ contentTags: :icons: font :experimental: +include::../_includes/partials/notes/server-api-examples.adoc[] + [#api-v2] == API v2 diff --git a/jekyll/_cci2/pipeline-variables.adoc b/jekyll/_cci2/pipeline-variables.adoc index 862f8d1c99c..a528200ca6f 100644 --- a/jekyll/_cci2/pipeline-variables.adoc +++ b/jekyll/_cci2/pipeline-variables.adoc @@ -93,6 +93,8 @@ jobs: [#passing-parameters-when-triggering-pipelines-via-the-api] === Passing parameters when triggering pipelines via the API +include::../_includes/partials/notes/server-api-examples.adoc[] + A pipeline can be triggered with specific `parameter` values using the API v2 endpoint to link:https://circleci.com/docs/api/v2/#trigger-a-new-pipeline[trigger a pipeline]. This can be done by passing a `parameters` key in the JSON packet of the `POST` body. The API limits the number of parameters that can be passed: diff --git a/jekyll/_cci2/workflows.adoc b/jekyll/_cci2/workflows.adoc index 88ff72903c1..dd9a362c033 100644 --- a/jekyll/_cci2/workflows.adoc +++ b/jekyll/_cci2/workflows.adoc @@ -222,6 +222,8 @@ To approve a job follow these steps: [.tab.approve.API] -- +include::../_includes/partials/notes/server-api-examples.adoc[] + . Set up your API authentication. Steps are available in the xref:api-developers-guide#add-an-api-token[API developers guide]. . You need your workflow ID and the `approval_request_id` (which is the job ID for the job requiring approval) to make the API POST request. Depending on your use case, you might be configuring an approval job in a pipeline, or using an external service to approve a job. You can get the required parameters using xref:variables#[pipeline values or environment variables], or by xref:webhooks#[receiving webhooks] or polling the API. To approve a job, use the link:https://circleci.com/docs/api/v2/index.html#operation/approvePendingApprovalJobById[approve a job] endpoint, for example: + diff --git a/jekyll/_includes/partials/notes/server-api-examples.adoc b/jekyll/_includes/partials/notes/server-api-examples.adoc new file mode 100644 index 00000000000..872cf60cc37 --- /dev/null +++ b/jekyll/_includes/partials/notes/server-api-examples.adoc @@ -0,0 +1 @@ +NOTE: **Using server?** If you are using CircleCI server, replace `https://circleci.com` with your server hostname when interacting with the CircleCI API. \ No newline at end of file