Better API documentation for packages

[harryzcy]

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

[lunny]

/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.

[KN4CK3R]

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.

[lunny]

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?

[KN4CK3R]

Yes, sorry, my mistake. Edited my comment.

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

[KN4CK3R]

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

[zeripath]

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
 }

[harryzcy]

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

Yes, my questions are cleared.