Fix google#257: Return http.Handler instead of SetupRouter in server/restapi/web (google#259)

* Add NewHandler() function to return http.Handler instead of requiring mux.Router - Created NewHandler() that returns standard http.Handler for better decoupling - Marked SetupRouter() as deprecated for backward compatibility - Allows users to use ADK REST API with any HTTP server/router, not just gorilla/mux

* Update api launcher to use NewHandler() instead of SetupRouter() - Refactored SetupSubrouters to use web.NewHandler() - Wraps handler with CORS middleware before registration - Uses http.StripPrefix for proper path handling - No breaking changes to web launcher interface

* Add example demonstrating NewHandler() usage with standard net/http - Shows how to use web.NewHandler() with net/http.ServeMux - Demonstrates framework-agnostic approach - Includes health check endpoint to show composability - Example works with any HTTP server/router, not tied to gorilla/mux

* Resolve PR feedback: remove SetupRouter and update example to use launcher.Config

* Clean up comments in NewHandler and setupRouter

Removed comments about the preferred integration method and the public SetupRouter helper.

* Fix linter issues: handle w.Write error and format with goimports

* Fix missing newline at end of api.go

Add a newline at the end of the file.

* Fix goimports formatting: remove trailing blank line and handle w.Write error

---------

Co-authored-by: Dmitry Pasiukevich <dpasiukevich@google.com>

Author: Arjunmehta312

cmd/launcher/web/api/api.go

@@ -67,9 +67,16 @@ func (a *apiLauncher) UserMessage(webURL string, printer func(v ...any)) {
 
 // SetupSubrouters adds the API router to the parent router.
 func (a *apiLauncher) SetupSubrouters(router *mux.Router, config *launcher.Config) error {
-	rAPI := router.Methods("GET", "POST", "DELETE", "OPTIONS").PathPrefix("/api/").Subrouter()
-	restapiweb.SetupRouter(rAPI, config)
-	rAPI.Use(corsWithArgs(a.config.frontendAddress))
+	// Create the ADK REST API handler
+	apiHandler := restapiweb.NewHandler(config)
+
+	// Wrap it with CORS middleware
+	corsHandler := corsWithArgs(a.config.frontendAddress)(apiHandler)
+
+	// Register it at the /api/ path
+	router.Methods("GET", "POST", "DELETE", "OPTIONS").PathPrefix("/api/").Handler(
+		http.StripPrefix("/api", corsHandler),
+	)
 	return nil
 }
 

examples/restapi/main.go

@@ -0,0 +1,93 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// This example demonstrates how to use the ADK REST API handler directly
+// with the standard net/http package, without relying on any specific router.
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os"
+
+	"google.golang.org/adk/agent/llmagent"
+	"google.golang.org/adk/cmd/launcher"
+	"google.golang.org/adk/model/gemini"
+	"google.golang.org/adk/server/restapi/services"
+	"google.golang.org/adk/server/restapi/web"
+	"google.golang.org/adk/session"
+	"google.golang.org/adk/tool"
+	"google.golang.org/adk/tool/geminitool"
+	"google.golang.org/genai"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Create a Gemini model
+	model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
+		APIKey: os.Getenv("GOOGLE_API_KEY"),
+	})
+	if err != nil {
+		log.Fatalf("Failed to create model: %v", err)
+	}
+
+	// Create an agent
+	agent, err := llmagent.New(llmagent.Config{
+		Name:        "weather_time_agent",
+		Model:       model,
+		Description: "Agent to answer questions about the time and weather in a city.",
+		Instruction: "I can answer your questions about the time and weather in a city.",
+		Tools: []tool.Tool{
+			geminitool.GoogleSearch{},
+		},
+	})
+	if err != nil {
+		log.Fatalf("Failed to create agent: %v", err)
+	}
+
+	// Configure the ADK REST API
+	config := &launcher.Config{
+		AgentLoader:    services.NewSingleAgentLoader(agent),
+		SessionService: session.InMemoryService(),
+	}
+
+	// Create the REST API handler - this returns a standard http.Handler
+	apiHandler := web.NewHandler(config)
+
+	// Create a standard net/http ServeMux
+	mux := http.NewServeMux()
+
+	// Register the API handler at the /api/ path
+	// You can use any HTTP server or router here - not tied to gorilla/mux
+	mux.Handle("/api/", http.StripPrefix("/api", apiHandler))
+
+	// Add a simple health check endpoint
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		if _, err := w.Write([]byte("OK")); err != nil {
+			log.Printf("Failed to write response: %v", err)
+		}
+	})
+
+	// Start the server
+	log.Println("Starting server on :8080")
+	log.Println("API available at http://localhost:8080/api/")
+	log.Println("Health check at http://localhost:8080/health")
+
+	if err := http.ListenAndServe(":8080", mux); err != nil {
+		log.Fatalf("Server failed: %v", err)
+	}
+}

server/restapi/web/server.go

@@ -16,6 +16,8 @@
 package web
 
 import (
+	"net/http"
+
 	"github.com/gorilla/mux"
 	"google.golang.org/adk/cmd/launcher"
 	"google.golang.org/adk/internal/telemetry"
@@ -26,18 +28,21 @@ import (
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 )
 
-// SetupRouter initiates mux.Router with ADK REST API routers
-func SetupRouter(router *mux.Router, routerConfig *launcher.Config) *mux.Router {
+// NewHandler creates and returns an http.Handler for the ADK REST API.
+func NewHandler(config *launcher.Config) http.Handler {
 	adkExporter := services.NewAPIServerSpanExporter()
 	telemetry.AddSpanProcessor(sdktrace.NewSimpleSpanProcessor(adkExporter))
-	return setupRouter(router,
-		routers.NewSessionsAPIRouter(handlers.NewSessionsAPIController(routerConfig.SessionService)),
-		routers.NewRuntimeAPIRouter(handlers.NewRuntimeAPIRouter(routerConfig.SessionService, routerConfig.AgentLoader, routerConfig.ArtifactService)),
-		routers.NewAppsAPIRouter(handlers.NewAppsAPIController(routerConfig.AgentLoader)),
-		routers.NewDebugAPIRouter(handlers.NewDebugAPIController(routerConfig.SessionService, routerConfig.AgentLoader, adkExporter)),
-		routers.NewArtifactsAPIRouter(handlers.NewArtifactsAPIController(routerConfig.ArtifactService)),
+
+	router := mux.NewRouter().StrictSlash(true)
+	setupRouter(router,
+		routers.NewSessionsAPIRouter(handlers.NewSessionsAPIController(config.SessionService)),
+		routers.NewRuntimeAPIRouter(handlers.NewRuntimeAPIRouter(config.SessionService, config.AgentLoader, config.ArtifactService)),
+		routers.NewAppsAPIRouter(handlers.NewAppsAPIController(config.AgentLoader)),
+		routers.NewDebugAPIRouter(handlers.NewDebugAPIController(config.SessionService, config.AgentLoader, adkExporter)),
+		routers.NewArtifactsAPIRouter(handlers.NewArtifactsAPIController(config.ArtifactService)),
 		&routers.EvalAPIRouter{},
 	)
+	return router
 }
 
 func setupRouter(router *mux.Router, subrouters ...routers.Router) *mux.Router {