Merge branch '219419-pypi-api-doc' into 'master'

Add PyPI API documentation See merge request gitlab-org/gitlab!57527

Merge branch '219419-pypi-api-doc' into 'master'
Add PyPI API documentation See merge request gitlab-org/gitlab!57527
c39d19e9 · Nick Gaskill · f7ab5c75 · d59342d5 · c39d19e9 · c39d19e9
Commit c39d19e9 authored Mar 25, 2021 by Nick Gaskill
Hide whitespace changes
Inline Side-by-side

Showing with 116 additions and 0 deletions

doc/api/packages/pypi.md doc/api/packages/pypi.md +113 -0

doc/user/packages/pypi_repository/index.md doc/user/packages/pypi_repository/index.md +3 -0

No files found.
--- a/doc/api/packages/pypi.md
+++ b/doc/api/packages/pypi.md
+---
+stage: Package
+group: Package
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+# PyPI API
+This is the API documentation for [PyPI Packages](../../user/packages/pypi_repository/index.md).
+WARNING:
+This API is used by the [PyPI package manager client](https://pypi.apache.org/)
+and is generally not meant for manual consumption.
+For instructions on how to upload and install PyPI packages from the GitLab
+package registry, see the [PyPI package registry documentation](../../user/packages/pypi_repository/index.md).
+NOTE:
+These endpoints do not adhere to the standard API authentication methods.
+See the [PyPI package registry documentation](../../user/packages/pypi_repository/index.md)
+for details on which headers and token types are supported.
+## Download a package file
+> Introduced in GitLab 12.10.
+Download a PyPI package file. The [simple API](#simple-api-entry-point)
+normally supplies this URL.
+```plaintext
+GET projects/:id/packages/pypi/files/:sha256/:file_identifier
+```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`              | string | yes | The ID or full path of the project. |
+| `sha256`          | string | yes | PyPI package file sha256 check sum. |
+| `file_identifier` | string | yes | The PyPI package file name. |
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz"
+```
+To write the output to a file:
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz
+```
+This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory.
+## Simple API entry point
+> Introduced in GitLab 12.10.
+Returns the package descriptor as an HTML file:
+```plaintext
+GET projects/:id/packages/pypi/simple/: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. |
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/simple/my.pypi.package"
+```
+Example response:
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Links for my.pypi.package</title>
+  </head>
+  <body>
+    <h1>Links for my.pypi.package</h1>
+    <a href="https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1-py3-none-any.whl#sha256=5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff" data-requires-python="&gt;=3.6">my.pypi.package-0.0.1-py3-none-any.whl</a><br><a href="https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/9s9w01b0bcd52b709ec052084e33a5517ffca96f7728ddd9f8866a30cdf76f2/my.pypi.package-0.0.1.tar.gz#sha256=9s9w011b0bcd52b709ec052084e33a5517ffca96f7728ddd9f8866a30cdf76f2" data-requires-python="&gt;=3.6">my.pypi.package-0.0.1.tar.gz</a><br>
+  </body>
+</html>
+```
+To write the output to a file:
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/simple/my.pypi.package" >> simple.html
+```
+This writes the downloaded file to `simple.html` in the current directory.
+## Upload a package
+> Introduced in GitLab 11.3.
+Upload a PyPI package:
+```plaintext
+PUT projects/:id/packages/pypi
+```
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | string | yes | The ID or full path of the project. |
+```shell
+curl --request PUT \
+     --upload-file path/to/my.pypi.package-0.0.1.tar.gz \
+     --user <username>:<personal_access_token> \
+     "https://gitlab.example.com/api/v4/projects/1/packages/pypi"
+```
--- a/doc/user/packages/pypi_repository/index.md
+++ b/doc/user/packages/pypi_repository/index.md
@@ -17,6 +17,9 @@ The Package Registry works with:
 - [pip](https://pypi.org/project/pip/)
 - [twine](https://pypi.org/project/twine/)
+For documentation of the specific API endpoints that the `pip` and `twine`
+clients use, see the [PyPI API documentation](../../../api/packages/pypi.md).
 ## Build a PyPI package
 This section explains how to create a PyPI package.