From edc77aab1401d5c2b024673a2ef3e208fdd77831 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 15:29:04 +0900 Subject: [PATCH 01/10] api docs for registry show --- pages/apis/rest_api/packages/registries.md | 30 ++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 33d84ee184..33b264021b 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -33,3 +33,33 @@ 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` \ No newline at end of file From 49e5edd9f1e1835d66ced64a6ee394e6d45f9807 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:00:51 +0900 Subject: [PATCH 02/10] api docs for registry create --- pages/apis/rest_api/packages/registries.md | 54 +++++++++++++++++++++- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 33b264021b..765716bd1e 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -2,6 +2,56 @@ The registries API lets you create and 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" + }' +``` + +```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": null, + "emoji": null, + "color": null, + "public": false, + "oidc_policy": null +} +``` + +Required [request body properties](/docs/api#request-body-properties): + + + + + + +
nameName of the new registry.
Example: "my registry".
ecosystemRegistry ecosystem based on the package ecosystem for the new registry.
Example: "ruby".
+ +Optional [request body properties](/docs/api#request-body-properties): + + + + + +
descriptionDescription of the registry.
Default value: null.
+ +Required scope: `create_registries` + +Success response: `200 OK` + ## List all registries Returns a list of an organization's registries. @@ -21,7 +71,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/packages/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": "registry containing ruby gems", + "description": null, "emoji": null, "color": null, "public": false, @@ -52,7 +102,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": "registry containing ruby gems", + "description": null, "emoji": null, "color": null, "public": false, From cb5e072aad65d65d2f61b7532e849a117be4d8e5 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:14:12 +0900 Subject: [PATCH 03/10] api docs for registry update --- pages/apis/rest_api/packages/registries.md | 51 ++++++++++++++++++++-- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 765716bd1e..74cf1eea83 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -10,7 +10,8 @@ curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "my registry", - "ecosystem": "ruby" + "ecosystem": "ruby", + "description": "registry containing ruby gems" }' ``` @@ -23,7 +24,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": null, + "description": "registry containing ruby gems", "emoji": null, "color": null, "public": false, @@ -71,7 +72,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/packages/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": null, + "description": "registry containing ruby gems", "emoji": null, "color": null, "public": false, @@ -102,7 +103,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": null, + "description": "registry containing ruby gems", "emoji": null, "color": null, "public": false, @@ -112,4 +113,46 @@ curl -H "Authorization: Bearer $TOKEN" \ 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): + + + + + + +
nameName of the registry.
Example: my registry.
descriptionDescription of the registry.
Example: registry containing ruby gems.
+ +Required scope: `write_registries` + Success response: `200 OK` \ No newline at end of file From e0172bf744c2afabe052993bcf60e3defb0c4687 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 15:29:04 +0900 Subject: [PATCH 04/10] api docs for registry show --- pages/apis/rest_api/packages/registries.md | 30 ++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 33d84ee184..2c95bd3e0c 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -33,3 +33,33 @@ 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` From 77f9ad5665a2d074743247aca4cb03f335266b5d Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:00:51 +0900 Subject: [PATCH 05/10] api docs for registry create --- pages/apis/rest_api/packages/registries.md | 56 ++++++++++++++++++++-- 1 file changed, 53 insertions(+), 3 deletions(-) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 33b264021b..b5c37cbad1 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -2,6 +2,56 @@ The registries API lets you create and 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" + }' +``` + +```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": null, + "emoji": null, + "color": null, + "public": false, + "oidc_policy": null +} +``` + +Required [request body properties](/docs/api#request-body-properties): + + + + + + +
nameName of the new registry.
Example: "my registry".
ecosystemRegistry ecosystem based on the package ecosystem for the new registry.
Example: "ruby".
+ +Optional [request body properties](/docs/api#request-body-properties): + + + + + +
descriptionDescription of the registry.
Default value: null.
+ +Required scope: `create_registries` + +Success response: `200 OK` + ## List all registries Returns a list of an organization's registries. @@ -21,7 +71,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/packages/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": "registry containing ruby gems", + "description": null, "emoji": null, "color": null, "public": false, @@ -52,7 +102,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": "registry containing ruby gems", + "description": null, "emoji": null, "color": null, "public": false, @@ -62,4 +112,4 @@ curl -H "Authorization: Bearer $TOKEN" \ Required scope: `read_registries` -Success response: `200 OK` \ No newline at end of file +Success response: `200 OK` From ca53b43eec8e7a630aef8644a1ffe877b9cd8fe2 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:14:12 +0900 Subject: [PATCH 06/10] api docs for registry update --- pages/apis/rest_api/packages/registries.md | 53 ++++++++++++++++++++-- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 765716bd1e..33fc90093a 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -10,7 +10,8 @@ curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "my registry", - "ecosystem": "ruby" + "ecosystem": "ruby", + "description": "registry containing ruby gems" }' ``` @@ -23,7 +24,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": null, + "description": "registry containing ruby gems", "emoji": null, "color": null, "public": false, @@ -71,7 +72,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/packages/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": null, + "description": "registry containing ruby gems", "emoji": null, "color": null, "public": false, @@ -102,7 +103,7 @@ curl -H "Authorization: Bearer $TOKEN" \ "web_url": "https://buildkite.com/organizations/my-org/registries/my-registry", "name": "my registry", "ecosystem": "ruby", - "description": null, + "description": "registry containing ruby gems", "emoji": null, "color": null, "public": false, @@ -112,4 +113,46 @@ curl -H "Authorization: Bearer $TOKEN" \ Required scope: `read_registries` -Success response: `200 OK` \ No newline at end of file +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): + + + + + + +
nameName of the registry.
Example: my registry.
descriptionDescription of the registry.
Example: registry containing ruby gems.
+ +Required scope: `write_registries` + +Success response: `200 OK` From ecafb614b731d80b6dfa8fa94a80976f59dd238f Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 16:18:10 +0900 Subject: [PATCH 07/10] api docs for registry delete --- pages/apis/rest_api/packages/registries.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index 74cf1eea83..cdfb0e3cfa 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -155,4 +155,15 @@ Optional [request body properties](/docs/api#request-body-properties): Required scope: `write_registries` -Success response: `200 OK` \ No newline at end of file +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` From f8a14c0df9c7d82e1ac7d28d93854ec02ec7ed72 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Wed, 11 Sep 2024 19:36:23 +0900 Subject: [PATCH 08/10] api docs for registry tokens index --- data/nav.yml | 6 ++- .../apis/rest_api/packages/registry_tokens.md | 50 +++++++++++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 pages/apis/rest_api/packages/registry_tokens.md diff --git a/data/nav.yml b/data/nav.yml index 605e8cae2e..0655d53365 100644 --- a/data/nav.yml +++ b/data/nav.yml @@ -557,7 +557,11 @@ - name: "Members" path: "apis/rest-api/organizations/members" pill: "beta" - - name: "Pipelines " + - name: "Packages" + children: + - name: "Registry Tokens" + path: "apis/rest-api/packages/registry-tokens" + - name: "Pipelines" children: - name: "Overview" path: "apis/rest-api/pipelines" diff --git a/pages/apis/rest_api/packages/registry_tokens.md b/pages/apis/rest_api/packages/registry_tokens.md new file mode 100644 index 0000000000..e8a1ce7965 --- /dev/null +++ b/pages/apis/rest_api/packages/registry_tokens.md @@ -0,0 +1,50 @@ +# Registry Tokens API + +The registry tokens API 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` From 5e4f2b5bd080b9d0f2750c4ad62566dab5df0962 Mon Sep 17 00:00:00 2001 From: Elizabeth Vo <65384387+ensvo@users.noreply.github.com> Date: Thu, 12 Sep 2024 12:11:14 +0900 Subject: [PATCH 09/10] fix scope naming mistake --- pages/apis/rest_api/packages/registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/packages/registries.md index c2ab576c01..265a368004 100644 --- a/pages/apis/rest_api/packages/registries.md +++ b/pages/apis/rest_api/packages/registries.md @@ -48,7 +48,7 @@ Optional [request body properties](/docs/api#request-body-properties): -Required scope: `create_registries` +Required scope: `write_registries` Success response: `200 OK` From 4e017fd740e17c4b512b7c9b6be85041ca1a8a12 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Thu, 12 Sep 2024 15:23:24 +1000 Subject: [PATCH 10/10] Fix heading in line with style guide and to please linter, as well as add word 'endpoint' for consistency across REST API docs. --- pages/apis/rest_api/packages/registry_tokens.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/apis/rest_api/packages/registry_tokens.md b/pages/apis/rest_api/packages/registry_tokens.md index e8a1ce7965..be8bf0e9a9 100644 --- a/pages/apis/rest_api/packages/registry_tokens.md +++ b/pages/apis/rest_api/packages/registry_tokens.md @@ -1,6 +1,6 @@ -# Registry Tokens API +# Registry tokens API -The registry tokens API lets you create and manage credentials needed to install and use packages in a registry. +The registry tokens API endpoint lets you create and manage credentials needed to install and use packages in a registry. ## List all registry tokens