Better API documentation for packages #9758

New Issue

GiteaMirror · 2025-11-02T08:48:44-06:00

GiteaMirror commented

2025-11-02 08:48:44 -06:00

Originally created by @harryzcy on GitHub (Oct 31, 2022).

Feature Description

Currently, the package registry APIs exists under several endpoints: /api/v1/packages, /api/packages, and /v2. It's not very clear how they are used and what's the difference between them.

Screenshots

No response

Originally created by @harryzcy on GitHub (Oct 31, 2022). ### Feature Description Currently, the package registry APIs exists under several endpoints: `/api/v1/packages`, `/api/packages`, and `/v2`. It's not very clear how they are used and what's the difference between them. ### Screenshots _No response_

GiteaMirror added the topic/packages type/docs labels 2025-11-02 08:48:44 -06:00

GiteaMirror closed this issue

2025-11-02 08:48:44 -06:00

GiteaMirror commented

2025-11-02 08:48:45 -06:00

@lunny commented on GitHub (Oct 31, 2022):

/api/v1/packages is for Gitea API users.

/api/packages and /v2 is for packages clients. /v2 exists I think maybe because that docker doesn't support sub path.

@lunny commented on GitHub (Oct 31, 2022): `/api/v1/packages` is for Gitea API users. `/api/packages` and `/v2` is for packages clients. `/v2` exists I think maybe because that docker doesn't support sub path.

GiteaMirror commented

2025-11-02 08:48:45 -06:00

@KN4CK3R commented on GitHub (Oct 31, 2022):

There should be no need to call the endpoints in /api/packages and /v2 because only the specific package client calls these. The only exception is the generic package type and these endpoints are already documented.

The documentation for the Gitea Package API can be found in the swagger section.

@KN4CK3R commented on GitHub (Oct 31, 2022): There should be no need to call the endpoints in `/api/packages` and `/v2` because only the specific package client calls these. The only exception is the `generic` package type and these endpoints are [already documented](https://docs.gitea.io/en-us/packages/generic/). The documentation for the Gitea Package API can be found in the [swagger section](https://gitea.com/api/swagger#/package).

GiteaMirror commented

2025-11-02 08:48:45 -06:00

@lunny commented on GitHub (Oct 31, 2022):

There should be no need to call the endpoints in /api/v1/packages and /v2 because only the specific package client calls these. The only exception is the generic package type and these endpoints are already documented.

The documentation for the Gitea Package API can be found in the swagger section.

IMO, maybe /api/packages is the right place where clients call but not api/v1/packages?

@lunny commented on GitHub (Oct 31, 2022): > There should be no need to call the endpoints in `/api/v1/packages` and `/v2` because only the specific package client calls these. The only exception is the `generic` package type and these endpoints are [already documented](https://docs.gitea.io/en-us/packages/generic/). > > The documentation for the Gitea Package API can be found in the [swagger section](https://gitea.com/api/swagger#/package). IMO, maybe `/api/packages` is the right place where clients call but not `api/v1/packages`?

GiteaMirror commented

2025-11-02 08:48:45 -06:00

@KN4CK3R commented on GitHub (Oct 31, 2022):

Yes, sorry, my mistake. Edited my comment.

Endpoint	Usage
`/v2/`	Docker CLI
`/api/packages/`	package managers (NuGet, npm, Maven, ...)
`/api/v1/packages/`	Gitea API

GiteaMirror commented

2025-11-02 08:48:45 -06:00

@KN4CK3R commented on GitHub (Oct 31, 2022):

@harryzcy Are your questions answered? Can this ticket be closed?

@KN4CK3R commented on GitHub (Oct 31, 2022): @harryzcy Are your questions answered? Can this ticket be closed?

GiteaMirror commented

2025-11-02 08:48:45 -06:00

@zeripath commented on GitHub (Oct 31, 2022):

It would be helpful to add these as comments where they are mounted and as comments on the functions e.g.

PATCH

diff --git a/routers/api/packages/api.go b/routers/api/packages/api.go
index 6f53bc4ae..a600e1a5c 100644
--- a/routers/api/packages/api.go
+++ b/routers/api/packages/api.go
@@ -40,7 +40,9 @@ func reqPackageAccess(accessMode perm.AccessMode) func(ctx *context.Context) {
 	}
 }
 
-func Routes(ctx gocontext.Context) *web.Route {
+// CommonRoutes provide endpoints for most package managers (excepting docker HUB - see below)
+// These are mounted on `/api/packages` (not `/api/v1/packages`)
+func CommonRoutes(ctx gocontext.Context) *web.Route {
 	r := web.NewRoute()
 
 	r.Use(context.PackageContexter(ctx))
@@ -301,7 +303,9 @@ func Routes(ctx gocontext.Context) *web.Route {
 	return r
 }
 
-func ContainerRoutes(ctx gocontext.Context) *web.Route {
+// DockerContainerRoutes provides endpoints that match the Docker HUB API in order for facilitate downloading packages a docker packages
+// These have to be mounted on `/v2/...` due to compatibility with the Docker HUB API
+func DockerContainerRoutes(ctx gocontext.Context) *web.Route {
 	r := web.NewRoute()
 
 	r.Use(context.PackageContexter(ctx))
diff --git a/routers/api/v1/api.go b/routers/api/v1/api.go
index 0d11674aa..bd22fac18 100644
--- a/routers/api/v1/api.go
+++ b/routers/api/v1/api.go
@@ -1073,6 +1073,7 @@ func Routes(ctx gocontext.Context) *web.Route {
 			}, repoAssignment())
 		})
 
+		// NOTE: these are Gitea package management API - see packages.CommonRoutes and packages.DockerContainerRoutes for endpoints to see implementations of package manager APIs
 		m.Group("/packages/{username}", func() {
 			m.Group("/{type}/{name}/{version}", func() {
 				m.Get("", packages.GetPackage)
diff --git a/routers/init.go b/routers/init.go
index 53b33f468..cb5e3beb1 100644
--- a/routers/init.go
+++ b/routers/init.go
@@ -185,9 +185,15 @@ func NormalRoutes(ctx context.Context) *web.Route {
 	r.Mount("/", web_routers.Routes(ctx))
 	r.Mount("/api/v1", apiv1.Routes(ctx))
 	r.Mount("/api/internal", private.Routes())
+
 	if setting.Packages.Enabled {
-		r.Mount("/api/packages", packages_router.Routes(ctx))
-		r.Mount("/v2", packages_router.ContainerRoutes(ctx))
+		// Add endpoints to match common package manager APIs
+
+		// This implements package support for most package managers
+		r.Mount("/api/packages", packages_router.CommonRoutes(ctx))
+
+		// This implements Docker HUB API (Note this is not preceded by /api but is instead /v2)
+		r.Mount("/v2", packages_router.DockerContainerRoutes(ctx))
 	}
 	return r
 }

@zeripath commented on GitHub (Oct 31, 2022): It would be helpful to add these as comments where they are mounted and as comments on the functions e.g. <details><summary>PATCH</summary> ```patch diff --git a/routers/api/packages/api.go b/routers/api/packages/api.go index 6f53bc4ae..a600e1a5c 100644 --- a/routers/api/packages/api.go +++ b/routers/api/packages/api.go @@ -40,7 +40,9 @@ func reqPackageAccess(accessMode perm.AccessMode) func(ctx *context.Context) { } } -func Routes(ctx gocontext.Context) *web.Route { +// CommonRoutes provide endpoints for most package managers (excepting docker HUB - see below) +// These are mounted on `/api/packages` (not `/api/v1/packages`) +func CommonRoutes(ctx gocontext.Context) *web.Route { r := web.NewRoute() r.Use(context.PackageContexter(ctx)) @@ -301,7 +303,9 @@ func Routes(ctx gocontext.Context) *web.Route { return r } -func ContainerRoutes(ctx gocontext.Context) *web.Route { +// DockerContainerRoutes provides endpoints that match the Docker HUB API in order for facilitate downloading packages a docker packages +// These have to be mounted on `/v2/...` due to compatibility with the Docker HUB API +func DockerContainerRoutes(ctx gocontext.Context) *web.Route { r := web.NewRoute() r.Use(context.PackageContexter(ctx)) diff --git a/routers/api/v1/api.go b/routers/api/v1/api.go index 0d11674aa..bd22fac18 100644 --- a/routers/api/v1/api.go +++ b/routers/api/v1/api.go @@ -1073,6 +1073,7 @@ func Routes(ctx gocontext.Context) *web.Route { }, repoAssignment()) }) + // NOTE: these are Gitea package management API - see packages.CommonRoutes and packages.DockerContainerRoutes for endpoints to see implementations of package manager APIs m.Group("/packages/{username}", func() { m.Group("/{type}/{name}/{version}", func() { m.Get("", packages.GetPackage) diff --git a/routers/init.go b/routers/init.go index 53b33f468..cb5e3beb1 100644 --- a/routers/init.go +++ b/routers/init.go @@ -185,9 +185,15 @@ func NormalRoutes(ctx context.Context) *web.Route { r.Mount("/", web_routers.Routes(ctx)) r.Mount("/api/v1", apiv1.Routes(ctx)) r.Mount("/api/internal", private.Routes()) + if setting.Packages.Enabled { - r.Mount("/api/packages", packages_router.Routes(ctx)) - r.Mount("/v2", packages_router.ContainerRoutes(ctx)) + // Add endpoints to match common package manager APIs + + // This implements package support for most package managers + r.Mount("/api/packages", packages_router.CommonRoutes(ctx)) + + // This implements Docker HUB API (Note this is not preceded by /api but is instead /v2) + r.Mount("/v2", packages_router.DockerContainerRoutes(ctx)) } return r } ``` </details>

GiteaMirror commented

2025-11-02 08:48:46 -06:00

@harryzcy commented on GitHub (Oct 31, 2022):

@harryzcy Are your questions answered? Can this ticket be closed?

Yes, my questions are cleared.

@harryzcy commented on GitHub (Oct 31, 2022): > @harryzcy Are your questions answered? Can this ticket be closed? Yes, my questions are cleared.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#9758