From a3d2dde5f79ff303b208bc9f73f703254fb96a1a Mon Sep 17 00:00:00 2001 From: Jonas Xavier Date: Fri, 27 Mar 2026 11:34:32 -0700 Subject: [PATCH] docs: clarify %2f encoding requirement for scoped package paths Scoped packages must encode the scope separator as %2f in the URL path. A literal slash is treated as two path segments and will not resolve. Registry implementations must preserve %2f without decoding it to / before routing. I'm not advocating for that solution, my goal is to document it for API compatiblity. --- docs/REGISTRY-API.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/REGISTRY-API.md b/docs/REGISTRY-API.md index e0fb487..5ddf0ed 100644 --- a/docs/REGISTRY-API.md +++ b/docs/REGISTRY-API.md @@ -108,11 +108,20 @@ This endpoint responds with the package metadata document, sometimes informally called a "packument" or "doc.json". The format of the response is described in detail in the [package metadata documentation](responses/package-metadata.md). +**Scoped packages:** The `{package}` path segment must be percent-encoded. The `/` separator between scope and name must be encoded as `%2f` (or `%2F`): + +``` +GET /@babel%2fcore +GET /@types%2fnode +``` + +A literal `/` in the path (e.g. `/@babel/core`) is treated as two separate path segments and will not resolve correctly. Registry implementations must not decode `%2f` to `/` before routing the request. + #### `GET·/{package}/{version}` | Name | Value | Kind | Required? | Notes | |------ |------- |------ |----------- |------- | -| package | String | **Path** | ✅ | the name of the package | +| package | String | **Path** | ✅ | the name of the package; scoped packages must use `%2f` for the `/` separator (e.g. `@babel%2fcore`) | | version | String | **Path** | ✅ | a version number or `latest` | #### `GET·/-/v1/search`