Merge pull request #43 from buildkite/fix-packages-api-example

Fix example in packages api that returns an error
buildkite · Sep 30, 2024 · f0f7d1b · f0f7d1b
2 parents 316436c + 76138fa
commit f0f7d1b
Show file tree

Hide file tree

Showing 7 changed files with 45 additions and 16 deletions.
diff --git a/data/nav.yml b/data/nav.yml
@@ -487,6 +487,8 @@
     - name: "Package ecosystems"
       start_expanded: true
       children:
+        - name: "Overview"
+          path: "packages/ecosystems"
         - name: "Alpine"
           path: "packages/alpine"
         - name: "Container"

diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/packages/packages.md
@@ -4,13 +4,34 @@ The packages API endpoint lets you create and manage packages in a registry.
 
 ## Publish a package
 
+The following type of `curl` syntax for publishing to registries will work across [all package ecosystems supported by Buildkite Packages](/docs/packages/ecosystems), with the `file` form-field modified accordingly.
+
 ```bash
 curl -H "Authorization: Bearer $TOKEN" \
   -X POST "https://api.buildkite.com/v2/packages/organizations/{org.slug}/registries/{registry.slug}/packages" \
-  -H "Content-Type: application/json" \
-  -F 'file=@path/to/ruby/gem/banana-1.0.0.gem'
+  -F 'file=@path/to/debian/package/banana_1.1-2_amd64.deb
 ```
 
+However, this type of REST API call is just recommended for:
+
+- [Alpine (apk)](/docs/packages/alpine#publish-a-package) packages
+- [Debian/Ubuntu (deb)](/docs/packages/debian#publish-a-package) packages
+- [Files (generic)](/docs/packages/files#publish-a-file)
+- [Helm (Standard)](/docs/packages/helm#publish-a-chart) charts
+- [Python (PyPI)](/docs/packages/python#publish-a-package) packages
+- [Red Hat (RPM)](/docs/packages/red-hat#publish-a-package) packages
+- [Terraform](/docs/packages/terraform#publish-a-module) modules
+
+For other supported package ecosystems, it is recommended that you use their native tools to publish to registries in your Buildkite Packages organization. These ecosystems' native tools are for:
+
+- [Container (Docker)](/docs/packages/container#publish-an-image) images
+- [Helm (OCI)](/docs/packages/helm-oci#publish-a-chart) charts
+- Java ([Maven](/docs/packages/maven#publish-a-package) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle#publish-a-package)) packages
+- [JavaScript (npm)](/docs/packages/javascript#publish-a-package) packages
+- [Ruby (RubyGems)](/docs/packages/ruby#publish-a-package) packages
+
+The following type of response is returned by Buildkite upon a successful `curl` publishing event.
+
 ```json
 {
   "id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
@@ -37,7 +58,7 @@ Required request form-field content:
 
 <table class="responsive-table">
 <tbody>
-  <tr><th><code>file</code></th><td>Path to the package.<br><em>Example:</em> <code>"file=@path/to/ruby/gem/banana-1.0.0.gem"</code>.</td></tr>
+  <tr><th><code>file</code></th><td>Path to the package.<br><em>Example:</em> <code>"file=@path/to/debian/package/banana_1.1-2_amd64.deb"</code>.</td></tr>
 </tbody>
 </table>
 

diff --git a/pages/packages/_supported_package_ecosystems.md b/pages/packages/_supported_package_ecosystems.md
@@ -0,0 +1,11 @@
+- [Alpine (apk)](/docs/packages/alpine)
+- [Container (Docker)](/docs/packages/container) images
+- [Debian/Ubuntu (deb)](/docs/packages/debian)
+- [Files (generic)](/docs/packages/files)
+- Helm ([OCI](/docs/packages/helm-oci) or [Standard](/docs/packages/helm))
+- Java ([Maven](/docs/packages/maven) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle))
+- [JavaScript (npm)](/docs/packages/javascript)
+- [Python (PyPI)](/docs/packages/python)
+- [Red Hat (RPM)](/docs/packages/red-hat)
+- [Ruby (RubyGems)](/docs/packages/ruby)
+- [Terraform](/docs/packages/terraform) modules
diff --git a/pages/packages/ecosystems.md b/pages/packages/ecosystems.md
@@ -0,0 +1,5 @@
+# Package ecosystems overview
+
+Buildkite Packages supports the following language and package ecosystems:
+
+<%= render_markdown partial: 'packages/supported_package_ecosystems' %>
diff --git a/pages/packages/helm.md b/pages/packages/helm.md
@@ -18,7 +18,7 @@ This command provides:
 - The API access token required to publish packages to your Helm registry.
 - The Helm package (`.tgz`) to be published.
 
-## Publishing a chart
+## Publish a chart
 
 The following `curl` command (which you'll need to modify as required before submitting) describes the process above to publish a Helm chart to your Helm registry:
 

diff --git a/pages/packages/helm_oci.md b/pages/packages/helm_oci.md
@@ -15,7 +15,7 @@ These Helm commands are used to:
 - Log in to your Buildkite Helm OCI registry with an API access token.
 - Publish a Helm chart to your registry.
 
-## Publishing a chart
+## Publish a chart
 
 The following steps describe the process above:
 

diff --git a/pages/packages/manage_registries.md b/pages/packages/manage_registries.md
@@ -25,17 +25,7 @@ To create a new registry:
 
 Once a [registry is created](#create-a-registry), packages can then be uploaded to it. Learn more about how to manage packages for your registry's relevant language and package ecosystem:
 
-- [Alpine (apk)](/docs/packages/alpine)
-- [Container (Docker)](/docs/packages/container) images
-- [Debian/Ubuntu (deb)](/docs/packages/debian)
-- [Files (generic)](/docs/packages/files)
-- Helm ([OCI](/docs/packages/helm-oci) or [Standard](/docs/packages/helm))
-- Java ([Maven](/docs/packages/maven) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle))
-- [JavaScript (npm)](/docs/packages/javascript)
-- [Python (PyPI)](/docs/packages/python)
-- [Red Hat (RPM)](/docs/packages/red-hat)
-- [Ruby (RubyGems)](/docs/packages/ruby)
-- [Terraform](/docs/packages/terraform) modules
+<%= render_markdown partial: 'packages/supported_package_ecosystems' %>
 
 ## Update a registry