Deprecating the end-point for fetching package archives. (#2374)
In practice we don't need it as the list-versions API end-point already
returns an `archive_url`. If we switch clients to use this `archive_url`
we can easily change the URL that packages are downloaded from. Most
cases where a package has to be downloaded the client has to resolve
versions first, hence, we already have to call the list versions API. In
the rare cases where know what version we want, but we haven't done a
resolution this will cost us an extra round-trip, however, this seems
acceptable.
We are deprecating the end-point because we discovered that it was
conflicting with other end-points on `pub.dev`. Specifically,
`pub.dev/packages/<verion>` conflicts with
`pub.dev/packages/<version>.tar.gz` because a semver version number can
have a pre-release ending in `.tar.gz´. Example: `1.0.0-dev.tar.gz` is a
legitimate semver version number.
Note. servers will still have to support the deprecated API end-point
indefinitely, otherwise old clients will stop working. But since the
conflict only affects packages with obscure version numbers this seems
acceptable. It just means that some old clients might have problems
downloading package with version numbers that ends in `.tar.gz`.
diff --git a/doc/repository-spec-v2.md b/doc/repository-spec-v2.md
index 4f00f58..e346339 100644
--- a/doc/repository-spec-v2.md
+++ b/doc/repository-spec-v2.md
@@ -44,7 +44,7 @@
"name": "<PACKAGE>",
"latest": {
"version": "<VERSION>",
- "archive_url": "<PUB_HOSTED_URL>/packages/<PACKAGE>/versions/<VERSION>.tar.gz",
+ "archive_url": "https://.../archive.tar.gz",
"pubspec": {
/* pubspec contents as JSON object */
}
@@ -52,7 +52,7 @@
"versions": [
{
"version": "<VERSION>",
- "archive_url": "<PUB_HOSTED_URL>/packages/<PACKAGE>/versions/<VERSION>.tar.gz",
+ "archive_url": "https://.../archive.tar.gz",
"pubspec": {
/* pubspec contents as JSON object */
}
@@ -62,9 +62,14 @@
}
```
+To fetch the package archive an HTTP `GET` request _following retries_ must be
+made to the URL given as `archive_url`. The response (after following redirects)
+must be a gzipped TAR archive.
+
### (Deprecated) Inspect a specific version of a package
**Deprecated** as of Dart 2.8, use "List all versions of a package" instead.
+Servers should still support this end-point for compatibility with older `pub` clients.
**GET** `<PUB_HOSTED_URL>/api/packages/<PACKAGE>/versions/<VERSION>`
@@ -77,14 +82,17 @@
```js
{
"version": "1.1.0",
- "archive_url": "<PUB_HOSTED_URL>/packages/<PACKAGE>/versions/<VERSION>.tar.gz",
+ "archive_url": "https://.../archive.tar.gz",
"pubspec": {
/* pubspec contents as JSON object */
}
}
```
-### Download a specific version of a package
+### (Deprecated) Download a specific version of a package
+
+**Deprecated** as of Dart 2.8, use the `archive_url` returned from the "List all versions of a package".
+Servers should still support this end-point for compatibility with older `pub` clients.
**GET** `<PUB_HOSTED_URL>/packages/<PACKAGE>/versions/<VERSION>.tar.gz`
