8.6 KiB
| stage | group | info |
|---|---|---|
| Package | Package | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.example/handbook/engineering/ux/technical-writing/#assignments |
npm API
This is the API documentation for npm Packages.
WARNING: This API is used by the npm package manager client and is not meant for manual consumption.
For instructions on how to upload and install npm packages from the GitLab package registry, see the npm package registry documentation.
NOTE: These endpoints do not adhere to the standard API authentication methods. See the npm package registry documentation for details on which headers and token types are supported.
Download a package
Introduced in GitLab 11.8.
Downloads the npm package. This URL is provided by the metadata endpoint.
GET projects/:id/packages/npm/:package_name/-/:file_name
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The ID or full path of the project. |
package_name |
string | yes | The name of the package. |
file_name |
string | yes | The name of the package file. |
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@my-scope/my-pkg-0.0.1.tgz"
Write the output to a file:
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@my-scope/my-pkg-0.0.1.tgz" >> @myscope/my-pkg-0.0.1.tgz
This writes the downloaded file to @myscope/my-pkg-0.0.1.tgz in the current directory.
Upload a package file
Introduced in GitLab 11.8.
Upload a package.
PUT projects/:id/packages/npm/:package_name
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The ID or full path of the project. |
package_name |
string | yes | The name of the package. |
versions |
string | yes | Package version info. |
curl --request PUT
--header "Content-Type: application/json"
--data @./path/to/metadata/file.json
--header "Authorization: Bearer <personal_access_token>" \
"https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg"
The metadata file content is generated by npm, but looks something like this:
{
"_attachments": {
"@myscope/my-pkg-1.3.7.tgz": {
"content_type": "application/octet-stream",
"data": "H4sIAAAAAAAAE+1TQUvDMBjdeb/iI4edZEldV2dPwhARPIjiyXlI26zN1iYhSeeK7L+bNJtednMg4l4OKe+9PF7DF0XzNS0ZVmEfr4wUgxODEJLEMRzjPRJyCYPJNCFRlCTE+dzH1PvJqYscQ2ss1a7KT3PCv8DX/kfwMQRAgjYMpYBuIoIzKtwy6MILG6YNl8Jr0XgyvgpswUyuubJ75TGMDuSaUcsKyDooa1C6De6G8t7GRcG2br4CGxKME3wDR1hmrLexvJKwQLdaS52CkOAFMIrlfMlZsUAwGgHbcgsRcid3fdqade9SFz7u9a1naGsrqX3gHbcPNINDyydWcmN1By+W19x2oU7NcyZMfwn3z/PAqTaruanmUix5+V3UXVKq9yEoRZW1yqQYl9zWNBvnssFUcbyJsdJyxXJrcHQdz8gsTg6PzGChGty3H+6Gvz0BZ5xxxn/FJ1EDRNIACAAA",
"length": 354
}
},
"_id": "@myscope/my-pkg",
"description": "Package created by me",
"dist-tags": {
"latest": "1.3.7"
},
"name": "@myscope/my-pkg",
"readme": "ERROR: No README data found!",
"versions": {
"1.3.7": {
"_id": "@myscope/my-pkg@1.3.7",
"_nodeVersion": "12.18.4",
"_npmVersion": "6.14.6",
"author": {
"name": "GitLab Package Registry Utility"
},
"description": "Package created by me",
"dist": {
"integrity": "sha512-loy16p+Dtw2S43lBmD3Nye+t+Vwv7Tbhv143UN2mwcjaHJyBfGZdNCTXnma3gJCUSE/AR4FPGWEyCOOTJ+ev9g==",
"shasum": "4a9dbd94ca6093feda03d909f3d7e6bd89d9d4bf",
"tarball": "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@myscope/my-pkg-1.3.7.tgz"
},
"keywords": [],
"license": "ISC",
"main": "index.js",
"name": "@myscope/my-pkg",
"publishConfig": {
"@myscope:registry": "https://gitlab.example.com/api/v4/projects/1/packages/npm"
},
"readme": "ERROR: No README data found!",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"version": "1.3.7"
}
}
}
Route prefix
For the remaining routes, there are two sets of identical routes that each make requests in different scopes:
- Use the instance-level prefix to make requests in the scope of the entire instance.
- Use the project-level prefix to make requests in a single project's scope.
The examples in this document all use the project-level prefix.
Instance-level
/packages/npm`
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The group ID or full group path. |
Project-level
/projects/:id/packages/npm`
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The project ID or full project path. |
Metadata
Introduced in GitLab 11.8.
Returns the metadata for a given package.
GET <route-prefix>/:package_name
| Attribute | Type | Required | Description |
|---|---|---|---|
package_name |
string | yes | The name of the package. |
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg"
Example response:
{
"name": "@myscope/my-pkg",
"versions": {
"0.0.2": {
"name": "@myscope/my-pkg",
"version": "0.0.1",
"dist": {
"shasum": "93abb605b1110c0e3cca0a5b805e5cb01ac4ca9b",
"tarball": "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@myscope/my-pkg-0.0.1.tgz"
}
}
},
"dist-tags": {
"latest": "0.0.1"
}
}
The URLs in the response have the same route prefix used to request them. If you request them with
the instance-level route, the returned URLs contain /api/v4/packages/npm.
Dist-Tags
List tags
Introduced in GitLab 12.7.
Lists the dist-tags for the package.
GET <route-prefix>/-/package/:package_name/dist-tags
| Attribute | Type | Required | Description |
|---|---|---|---|
package_name |
string | yes | The name of the package. |
curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/npm/-/package/@myscope/my-pkg/dist-tags"
Example response:
{
"latest": "2.1.1",
"stable": "1.0.0"
}
The URLs in the response have the same route prefix used to request them. If you request them with
the instance-level route, the returned URLs contain /api/v4/packages/npm.
Create or update a tag
Introduced in GitLab 12.7.
Create or update a dist-tag.
PUT <route-prefix>/-/package/:package_name/dist-tags/:tag
| Attribute | Type | Required | Description |
|---|---|---|---|
package_name |
string | yes | The name of the package. |
tag |
string | yes | The tag to be created or updated. |
version |
string | yes | The version to be tagged. |
curl --request PUT --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/npm/-/package/@myscope/my-pkg/dist-tags/stable"
This endpoint responds successfully with 204 No Content.
Delete a tag
Introduced in GitLab 12.7.
Delete a dist-tag.
DELETE <route-prefix>/-/package/:package_name/dist-tags/:tag
| Attribute | Type | Required | Description |
|---|---|---|---|
package_name |
string | yes | The name of the package. |
tag |
string | yes | The tag to be created or updated. |
curl --request DELETE --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/npm/-/package/@myscope/my-pkg/dist-tags/stable"
This endpoint responds successfully with 204 No Content.