Merge branch 'main' into ev-packages-api-packages-show

buildkite · Sep 12, 2024 · 59dcc8e · 59dcc8e
2 parents b8e7ba5 + 630d823
commit 59dcc8e
Show file tree

Hide file tree

Showing 3 changed files with 186 additions and 0 deletions.
diff --git a/data/nav.yml b/data/nav.yml
@@ -563,6 +563,8 @@
           children:
             - name: "Registries"
               path: "apis/rest-api/packages/registries"
+            - name: "Registry Tokens"
+              path: "apis/rest-api/packages/registry-tokens"
             - name: "Packages"
               path: "apis/rest-api/packages/packages"
         - name: "Pipelines "

diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md
@@ -2,6 +2,57 @@
 
 The registries API endpoint lets you [create and manage registries](/docs/packages/manage-registries) in your organization.
 
+## Create a registry
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X POST "https://api.buildkite.com/v2/packages/organizations/#{org.slug}/registries" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my registry",
+    "ecosystem": "ruby",
+    "description": "registry containing ruby gems"
+    }' 
+```
+
+```json
+{
+  "id": "0191df84-85e4-77aa-83ba-6579084728eb",
+  "graphql_id": "UmVnaXN0cnktLS0wMTkxZGY4NC04NWU0LTc3YWEtODNiYS02NTc5MDg0NzI4ZWI=",
+  "slug": "my-registry",
+  "url": "https://api.buildkite.com/v2/packages/organizations/my-org/registries/my-registry",
+  "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry",
+  "name": "my registry",
+  "ecosystem": "ruby",
+  "description": "registry containing ruby gems",
+  "emoji": null,
+  "color": null,
+  "public": false,
+  "oidc_policy": null
+}
+```
+
+Required [request body properties](/docs/api#request-body-properties):
+
+<table class="responsive-table">
+<tbody>
+  <tr><th><code>name</code></th><td>Name of the new registry.<br><em>Example:</em> <code>"my registry"</code>.</td></tr>
+  <tr><th><code>ecosystem</code></th><td>Registry ecosystem based on the <a href="/docs/packages#get-started">package ecosystem</a> for the new registry.<br><em>Example:</em> <code>"ruby"</code>.</td></tr>
+</tbody>
+</table>
+
+Optional [request body properties](/docs/api#request-body-properties):
+
+<table class="responsive-table">
+  <tbody>
+    <tr><th><code>description</code></th><td>Description of the registry.<br><em>Default value:</em> <code>null</code>.</td></tr>
+  </tbody>
+</table>
+
+Required scope: `write_registries`
+
+Success response: `200 OK`
+
 ## List all registries
 
 Returns a list of an organization's registries.
@@ -33,3 +84,86 @@ curl -H "Authorization: Bearer $TOKEN" \
 Required scope: `read_registries`
 
 Success response: `200 OK`
+
+## Get a registry
+
+Returns the details for a single registry, looked up by its slug.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X GET "https://api.buildkite.com/v2/packages/organizations/#{org.slug}/registries/#{registry.slug}"
+```
+
+```json
+{
+  "id": "0191df84-85e4-77aa-83ba-6579084728eb",
+  "graphql_id": "UmVnaXN0cnktLS0wMTkxZGY4NC04NWU0LTc3YWEtODNiYS02NTc5MDg0NzI4ZWI=",
+  "slug": "my-registry",
+  "url": "https://api.buildkite.com/v2/packages/organizations/my-org/registries/my-registry",
+  "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry",
+  "name": "my registry",
+  "ecosystem": "ruby",
+  "description": "registry containing ruby gems",
+  "emoji": null,
+  "color": null,
+  "public": false,
+  "oidc_policy": null
+}
+```
+
+Required scope: `read_registries`
+
+Success response: `200 OK`
+
+## Update a registry
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X POST "https://api.buildkite.com/v2/packages/organizations/#{org.slug}/registries/#{registry.slug}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my registry",
+    "description": "registry containing ruby gems"
+    }' 
+```
+
+```json
+{
+  "id": "0191df84-85e4-77aa-83ba-6579084728eb",
+  "graphql_id": "UmVnaXN0cnktLS0wMTkxZGY4NC04NWU0LTc3YWEtODNiYS02NTc5MDg0NzI4ZWI=",
+  "slug": "my-registry",
+  "url": "https://api.buildkite.com/v2/packages/organizations/my-org/registries/my-registry",
+  "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry",
+  "name": "my registry",
+  "ecosystem": "ruby",
+  "description": "registry containing ruby gems",
+  "emoji": null,
+  "color": null,
+  "public": false,
+  "oidc_policy": null
+}
+```
+
+Optional [request body properties](/docs/api#request-body-properties):
+
+<table class="responsive-table">
+  <tbody>
+    <tr><th><code>name</code></th><td>Name of the registry.<br><em>Example:</em> <code>my registry</code>.</td></tr>
+    <tr><th><code>description</code></th><td>Description of the registry.<br><em>Example:</em> <code>registry containing ruby gems</code>.</td></tr>
+  </tbody>
+</table>
+
+Required scope: `write_registries`
+
+Success response: `200 OK`
+
+## Delete a registry
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X DELETE "https://api.buildkite.com/v2/packages/organizations/#{org.slug}/registries/#{registry.slug}"
+```
+
+Required scope: `delete_registries`
+
+Success response: `200 OK`
diff --git a/pages/apis/rest_api/packages/registry_tokens.md b/pages/apis/rest_api/packages/registry_tokens.md
@@ -0,0 +1,50 @@
+# Registry tokens API
+
+The registry tokens API endpoint lets you create and manage credentials needed to install and use packages in a registry.
+
+## List all registry tokens
+
+Returns a list of a registry's tokens.
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X GET "https://api.buildkite.com/v2/packages/organizations/#{org.slug}/registries/#{registry.slug}/tokens" \
+  -H "Content-Type: application/json"
+```
+
+```json
+[
+  {
+    "id": "0191b6a2-aa51-70d0-8a5f-aabce115b0fd",
+    "graphql_id": "UmVnaXN0cnlUb2tlbi0tLTAxOTFiNmEyLWFhNTEtNzBkMC04YTVmLWFhYmNlMTE1YjBmZA==",
+    "description": "Usher",
+    "url": "http://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry/tokens/0191b6a2-aa51-70d0-8a5f-aabce115b0fd",
+    "created_at": "2024-09-03T06:46:39.441Z",
+    "created_by": {
+      "id": "0191b13b-0eb6-470d-a4c0-2085974f3580",
+      "graphql_id": "VXNlci0tLTAxOTFiMTNiLTBlYjYtNDcwZC1hNGMwLTIwODU5NzRmMzU4MA==",
+      "name": "Eminem",
+      "email": "eminem@buildkite.com",
+      "avatar_url": null,
+      "created_at": "2024-09-02T05:35:23.318Z"
+    },
+    "organization": {
+      "id": "018a456f-e581-44b6-c5a4-1d8a5f7094ee",
+      "slug": "my_great_org",
+      "url": "https://api.buildkite.com/v2/analytics/organizations/my_great_org",
+      "web_url": "https://buildkite.com/organizations/my_great_org"
+    },
+    "registry": {
+      "id": "018f56ef-9ef4-70f0-aba2-0f4578e3d69d",
+      "graphql_id": "UmVnaXN0cnktLS0wMThmNTZlZi05ZWY0LTcwZjAtYWJhMi0wZjQ1NzhlM2Q2OWQ=",
+      "slug": "my-registry",
+      "url": "http://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry",
+      "web_url": "http://buildkite.com/organizations/buildkite/my_great_org/registries/my-registry"
+    }
+  }
+]
+```
+
+Required scope: `read_registries`
+
+Success response: `200 OK`