Porting an API from Another Language

Capture the contract you must honour

Before writing Go, produce a machine-readable description of the existing API. In order of preference:

1. An OpenAPI/Swagger document the old service already generates.
2. Recorded traffic — a day of real requests and responses from the access log or proxy.
3. The route table plus the tests, read by hand.

You need, for every endpoint: method, path, path/query parameters, request body fields with types and required-ness, response body shape, every status code it can return, and what authentication it requires.

Checkpoint: a list of endpoints that you and the API's consumers agree is complete.

Stand up the skeleton

go get -u github.com/klass-lk/ginboot

Use start.ginboot.com to scaffold, or create the layout by hand:

package main

import (
	"log"

	"github.com/klass-lk/ginboot"
)

func main() {
	server := ginboot.New()
	cfg := server.Config()
	server.SetBasePath(cfg.Ginboot.Server.BasePath)

	// Controllers are registered here as you port them.

	log.Fatal(server.Start(cfg.Ginboot.Server.Port))
}

Checkpoint: curl localhost:8080/healthz returns {"status":"UP",...}.

Port the models

Translate each entity once, with the tags the target backend needs. Go's zero values are the trap here: a missing JSON field and an explicitly-sent 0 or "" are indistinguishable unless you use a pointer.

type User struct {
	ID        string    `json:"id"        bson:"_id" ginboot:"_id"`
	Email     string    `json:"email"     bson:"email"`
	Name      string    `json:"name"      bson:"name"`
	Age       *int      `json:"age"       bson:"age"` // nullable: pointer
	CreatedAt time.Time `json:"createdAt" bson:"created_at"`
}

Checkpoint: a round-trip test that unmarshals a recorded response body from the old API into your struct, marshals it back, and compares.

Port the business logic into services

Services hold the rules and must not import the web framework. They take a context.Context where the old code took a request or session, and they return domain errors.

type UserService struct {
	repo *repository.UserRepository
}

func (s *UserService) Register(req model.RegisterRequest) (model.User, error) {
	exists, err := s.repo.ExistsBy("email", req.Email)
	if err != nil {
		return model.User{}, err
	}
	if exists {
		return model.User{}, ErrEmailTaken.New(req.Email)
	}
	// ... the same rules the old service had ...
	return user, s.repo.Save(user)
}

This is the step where a port usually goes wrong: hidden behaviour. Implicit ORM callbacks, request-scoped globals, Django signals, Rails before_save hooks and Spring aspects do not exist in Go. Every one of them has to become an explicit call, and finding them means reading the old code rather than the old routes.

Checkpoint: service-level unit tests, ported from the old test suite where one exists.

Port the data layer

Pick the repository module for your backend and point it at the same database the old service uses, so the two implementations can run side by side:

go get github.com/klass-lk/ginboot/db/mongo   # or /db/sql, /db/dynamodb

import dbMongo "github.com/klass-lk/ginboot/db/mongo"

type UserRepository struct {
	*dbMongo.MongoRepository[model.User]
}

func NewUserRepository(db *mongo.Database) *UserRepository {
	return &UserRepository{
		MongoRepository: dbMongo.NewMongoRepository[model.User](db, "users"),
	}
}

Two things do not come across, and pretending otherwise causes production surprises:

• Lazy loading and eager relations. There is no include, select_related or @OneToMany fetch. Related data is a second call, or a field you store denormalised.
• Schema migrations. Ginboot does not manage schema. Keep the migration tool the old stack used, or adopt one — but the schema stays owned by exactly one system.

Checkpoint: the repository reads real rows written by the old service and produces identical values.

Port the handlers

Handlers should be thin: bind, delegate, return. Ginboot binds and validates the request before your function runs.

// Before
router.post('/users', async (req, res) => {
  const { email, name } = req.body;
  if (!email) return res.status(400).json({ error: 'email required' });
  try {
    const user = await userService.register({ email, name });
    res.status(201).json(user);
  } catch (err) {
    res.status(409).json({ error: err.message });
  }
});

// After
type RegisterRequest struct {
	Email string `json:"email" binding:"required,email"`
	Name  string `json:"name"  binding:"required"`
}

func (c *UserController) Register(group *ginboot.ControllerGroup) {
	group.POST("", c.Create)
}

func (c *UserController) Create(req RegisterRequest) (model.User, error) {
	return c.users.Register(req)
}

ctx.JSON(http.StatusCreated, user)
return nil, nil

Checkpoint: for each ported endpoint, the same request returns the same body and status as the old service.

Port validation and errors

binding tags come from go-playground/validator; a failure becomes a 400 before your handler runs.

Declare the API's error vocabulary once, and give each error the status code the old API used:

var (
	ErrUserNotFound = ginboot.NewApiError(404, "User with ID %s not found")
	ErrEmailTaken   = ginboot.NewApiError(409, "Email %s is already registered")
	ErrForbidden    = ginboot.NewApiError(403, "Operation not permitted")
)

Every response body then has the same shape, and an unmapped internal error becomes a 500 rather than leaking:

{ "error_code": "404", "message": "User with ID 42 not found" }

Port authentication

Authentication is middleware. Whatever verifies the token must set two keys, because ctx.GetAuthContext() reads exactly these:

func Auth() gin.HandlerFunc {
	return func(c *gin.Context) {
		raw := strings.TrimPrefix(c.GetHeader("Authorization"), "Bearer ")

		token, err := ginboot.ParseAccessToken(raw)
		if err != nil {
			c.AbortWithStatus(http.StatusUnauthorized)
			return
		}
		claims, err := ginboot.ExtractClaims(token)
		if err != nil || ginboot.IsExpired(claims) {
			c.AbortWithStatus(http.StatusUnauthorized)
			return
		}

		c.Set("user_id", ginboot.ExtractUserId(claims))
		c.Set("role", ginboot.ExtractRole(claims))
		c.Next()
	}
}

protected := group.Group("", middleware.Auth())
protected.GET("/me", c.Me)

Sessions are the one case that needs a decision rather than a translation. If the old API authenticated with server-side sessions (Django, Rails, Laravel, Spring Session), you are choosing between sharing the session store, or issuing JWTs and migrating clients. Decide this before the cutover, not during it.

See Authentication for JWT helpers and PBKDF2 password hashing — including how to keep verifying hashes produced by the old stack.

Port scheduled jobs and queue consumers

server.RegisterWorker("expire-sessions", time.Hour, func(ctx context.Context) error {
	return svc.PurgeExpiredSessions(ctx)
})

server.RegisterConsumer(ginboot.NewQueueConsumer("sms", ginboot.Queue("sms"),
	func(ctx context.Context, msg model.SMS) error {
		return smsService.Send(ctx, msg)
	}))

See Background Workers and Event Triggers.

Cut traffic over, path by path

Put both services behind the same proxy or load balancer, and move routes across individually:

            ┌──────────────┐
  clients → │ proxy / ALB  │
            └──────┬───────┘
                   │  /api/v1/users/*   → ginboot service   (ported)
                   │  /api/v1/orders/*  → ginboot service   (ported)
                   │  /api/v1/*         → legacy service    (not yet)

A practical order:

1. Read-only endpoints first — a wrong response is recoverable, a wrong write is not.
2. Low-traffic write endpoints next.
3. The core write paths last, after the earlier ones have run for a while under real load.

Two techniques are worth the effort on any API that matters:

• Shadow traffic. Send a copy of production requests to the new service and diff the responses, without returning them to clients. It finds the field you renamed by accident and the timestamp format you changed.
• Contract tests. Write each endpoint's behaviour once in Gherkin and run it against both services. Ginboot ships Godog step definitions for exactly this — see Testing & BDD.

Keep the rollback simple: one proxy rule per path, so reverting is one change.

Checkpoint: the old service receives no traffic for a full business cycle — including month-end, if that is a thing in your domain — before you delete it.