Repository: bacalhau-project/bacalhau (language: python)

Issue:
Return HTTP 410 for legacy API methods
Returning a helpful message like:
```
{
  "message": "This endpoint is deprecated and no longer available. Please use /new-endpoint.",
  "new_parameters": "Refer to the new API documentation for updated parameters."
}
```
when a deprecated method is called.


Discussion / hints:

Fix patch:
diff --git a/pkg/publicapi/endpoint/requester/endpoint.go b/pkg/publicapi/endpoint/requester/endpoint.go
index ae0331da99..3c2f9adfa9 100644
--- a/pkg/publicapi/endpoint/requester/endpoint.go
+++ b/pkg/publicapi/endpoint/requester/endpoint.go
@@ -1,15 +1,19 @@
 package requester
 
 import (
+	"fmt"
+	"net/http"
+	"os"
 	"sync"
 
+	"github.com/gorilla/websocket"
+	"github.com/labstack/echo/v4"
+
 	"github.com/bacalhau-project/bacalhau/pkg/jobstore"
 	"github.com/bacalhau-project/bacalhau/pkg/model"
 	"github.com/bacalhau-project/bacalhau/pkg/orchestrator"
 	"github.com/bacalhau-project/bacalhau/pkg/publicapi/middleware"
 	"github.com/bacalhau-project/bacalhau/pkg/requester"
-	"github.com/gorilla/websocket"
-	"github.com/labstack/echo/v4"
 )
 
 type EndpointParams struct {
@@ -31,6 +35,8 @@ type Endpoint struct {
 	websocketsMutex sync.RWMutex
 }
 
+const UseDeprecatedEndpointsForTesting = "REQUESTER_ENDPOINT_USE_DEPRECATED_ENV"
+
 func NewEndpoint(params EndpointParams) *Endpoint {
 	e := &Endpoint{
 		router:             params.Router,
@@ -43,15 +49,42 @@ func NewEndpoint(params EndpointParams) *Endpoint {
 
 	g := e.router.Group("/api/v1/requester")
 	g.Use(middleware.SetContentType(echo.MIMEApplicationJSON))
-	g.POST("/list", e.list)
-	g.GET("/nodes", e.nodes)
-	g.POST("/states", e.states)
-	g.POST("/results", e.results)
-	g.POST("/events", e.events)
-	g.POST("/submit", e.submit)
-	g.POST("/cancel", e.cancel)
-	g.POST("/debug", e.debug)
-	g.GET("/websocket/events", e.websocketJobEvents)
+	if key := os.Getenv(UseDeprecatedEndpointsForTesting); key != "" {
+		g.POST("/list", e.list)
+		g.GET("/nodes", e.nodes)
+		g.POST("/states", e.states)
+		g.POST("/results", e.results)
+		g.POST("/events", e.events)
+		g.POST("/submit", e.submit)
+		g.POST("/cancel", e.cancel)
+		g.POST("/debug", e.debug)
+		g.GET("/websocket/events", e.websocketJobEvents)
+		return e
+	}
 
+	registerDeprecatedLegacyMethods(g)
 	return e
 }
+
+// registerDeprecatedLegacyMethods registers routes on the router that are 'Gone'.
+func registerDeprecatedLegacyMethods(group *echo.Group) {
+	// Legacy API Endpoints
+	// All return status 410 https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410
+	group.POST("/list", methodGone("https://docs.bacalhau.org/references/api/jobs#list-jobs"))
+	group.GET("/nodes", methodGone("https://docs.bacalhau.org/references/api/nodes#list-nodes"))
+	group.POST("/states", methodGone("https://docs.bacalhau.org/references/api/jobs#describe-job"))
+	group.POST("/results", methodGone("https://docs.bacalhau.org/references/api/jobs#describe-job"))
+	group.POST("/events", methodGone("https://docs.bacalhau.org/references/api/jobs#job-history"))
+	group.POST("/submit", methodGone("https://docs.bacalhau.org/references/api/jobs#create-job"))
+	group.POST("/cancel", methodGone("https://docs.bacalhau.org/references/api/jobs#stop-job"))
+	group.POST("/debug", methodGone("https://docs.bacalhau.org/references/api/nodes#describe-node"))
+	group.GET("/websocket/events", methodGone("https://docs.bacalhau.org/references/api/jobs#job-history"))
+}
+
+const deprecationMessage = "This endpoint is deprecated and no longer available. Please refer to %s for more information. If you encountered this error using the Bacalhau client or CLI, please update your node by following the instructions here: https://docs.bacalhau.org/getting-started/installation" //nolint:lll
+
+func methodGone(docsLink string) func(c echo.Context) error {
+	return func(c echo.Context) error {
+		return c.JSON(http.StatusGone, fmt.Sprintf(deprecationMessage, docsLink))
+	}
+}


Test patch:
diff --git a/pkg/publicapi/test/util_test.go b/pkg/publicapi/test/util_test.go
index 1a04a25882..00cbd1e011 100644
--- a/pkg/publicapi/test/util_test.go
+++ b/pkg/publicapi/test/util_test.go
@@ -2,6 +2,7 @@ package test
 
 import (
 	"context"
+	"os"
 	"path/filepath"
 	"testing"
 
@@ -10,6 +11,7 @@ import (
 	"github.com/bacalhau-project/bacalhau/pkg/compute/store/boltdb"
 	"github.com/bacalhau-project/bacalhau/pkg/config/types"
 	boltjobstore "github.com/bacalhau-project/bacalhau/pkg/jobstore/boltdb"
+	"github.com/bacalhau-project/bacalhau/pkg/publicapi/endpoint/requester"
 
 	"github.com/bacalhau-project/bacalhau/pkg/devstack"
 	"github.com/bacalhau-project/bacalhau/pkg/lib/network"
@@ -72,6 +74,9 @@ func setupNodeForTestWithConfig(t *testing.T, apiCfg publicapi.Config) (*node.No
 		NetworkConfig:       networkConfig,
 	}
 
+	if err := os.Setenv(requester.UseDeprecatedEndpointsForTesting, "true"); err != nil {
+		t.Fatal(err)
+	}
 	n, err := node.NewNode(ctx, c, nodeConfig, repo)
 	require.NoError(t, err)
 
diff --git a/pkg/test/teststack/stack.go b/pkg/test/teststack/stack.go
index 9464d578b9..47501449ef 100644
--- a/pkg/test/teststack/stack.go
+++ b/pkg/test/teststack/stack.go
@@ -4,6 +4,7 @@ package teststack
 
 import (
 	"context"
+	"os"
 	"testing"
 	"time"
 
@@ -18,6 +19,7 @@ import (
 	"github.com/bacalhau-project/bacalhau/pkg/model"
 	"github.com/bacalhau-project/bacalhau/pkg/models"
 	"github.com/bacalhau-project/bacalhau/pkg/node"
+	"github.com/bacalhau-project/bacalhau/pkg/publicapi/endpoint/requester"
 	"github.com/bacalhau-project/bacalhau/pkg/repo"
 	"github.com/bacalhau-project/bacalhau/pkg/system"
 )
@@ -49,6 +51,9 @@ func Setup(
 	t.Cleanup(func() {
 		cm.Cleanup(ctx)
 	})
+	if err := os.Setenv(requester.UseDeprecatedEndpointsForTesting, "true"); err != nil {
+		t.Fatal(err)
+	}
 	stack, err := devstack.Setup(ctx, cfg, cm, fsr, append(testDevStackConfig().Options(), opts...)...)
 	if err != nil {
 		t.Fatalf("creating teststack: %s", err)