Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[PKG-6905] API docs for packages create #2980

Merged
merged 6 commits into from
Sep 13, 2024
Merged

[PKG-6905] API docs for packages create #2980

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dd0cb89
api docs for package create
ensvo Sep 11, 2024
295d334
reword upload to publish
ensvo Sep 12, 2024
fb6df0c
Merge remote-tracking branch 'docs-public/main' into ev-packages-api-…
gilesgas Sep 12, 2024
24d4bda
Fix nav.
gilesgas Sep 12, 2024
7cd7d2e
Merge remote-tracking branch 'docs-public/main' into ev-packages-api-…
gilesgas Sep 12, 2024
a3d4022
Fix typo for packages API endpoint
ensvo Sep 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 44 additions & 1 deletion pages/apis/rest_api/packages/packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,49 @@
# Packages API

The packages tokens API lets you create and manage packages in a registry.
The packages API endpoint lets you create and manage packages in a registry.

## Publish a package

```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'
```

```json
{
"id": "0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
"url": "https://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry/packages/0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
"web_url": "https://buildkite.com/organizations/my_great_org/packages/registries/my-registry/packages/0191e23a-4bc8-7683-bfa4-5f73bc9b7c44",
"name": "banana",
"organization": {
"id": "0190e784-eeb7-4ce4-9d2d-87f7aba85433",
"slug": "my_great_org",
"url": "https://api.buildkite.com/v2/organizations/my_great_org",
"web_url": "https://buildkite.com/my_great_org"
},
"registry": {
"id": "0191e238-e0a3-7b0b-bb34-beea0035a39d",
"graphql_id": "UmVnaXN0cnktLS0wMTkxZTIzOC1lMGEzLTdiMGItYmIzNC1iZWVhMDAzNWEzOWQ=",
"slug": "my-registry",
"url": "https://api.buildkite.com/v2/packages/organizations/my_great_org/registries/my-registry",
"web_url": "https://buildkite.com/organizations/my_great_org/packages/registries/my-registry"
}
}
```

Required request form-field content:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK this is the first instance of a file upload using the API here - I'm curious to know if this part looks and reads fine.
I've referenced the curl manpage for -F specifying a file as the content type: https://curl.se/docs/manpage.html#-F

Copy link
Contributor

@gilesgas gilesgas Sep 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good!

I think you're correct, we haven't really used form field inputs for any of the other Buildkite REST API endpoints before, so we might add a cross-reference-able section to this section once we indicate there that form fields can also be accepted.


<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>
</tbody>
</table>

Required scope: `create_packages`

Success response: `200 OK`

## Get a package

Expand Down
Loading