Framework
Implementing a new operation
An operation is a single method or function that a caller can invoke. In an HTTP API context it's often called a route or endpoint.
This framework promotes a bottom-up approach to building APIs.
The first step to implementing a new operation is to define the request and response types along with an operation function.
type Request struct {
// request params
}
type Response struct {
// response data
}
func Operation(ctx context.Context, req Request) (Response, error) {
// operation logic
}
Alternatively, the operation function can be defined as a method on a struct.
type Service struct {
}
func (s Service) Operation(ctx context.Context, req Request) (Response, error) {
// operation logic
}
In case of an HTTP API, the next step is to define encoding and decoding functions for request, response and errors.
func DecodeOperationRequest(ctx context.Context, r *http.Request) (Request, error) {
// decode request
}
func EncodeOperationResponse(ctx context.Context, w http.ResponseWriter, response Response) error {
// encode response
}
func EncodeOperationError(ctx context.Context, err error, w http.ResponseWriter) bool {
// encode error
// return true if the error is considered "handled", false otherwise (error gets passed to the error handler)
return true
}
Finally, create a constructor function for the HTTP handler.
func NewOperationHandler(op operation.Operation[Request, Response], errorHandler httptransport.ErrorHandler) http.Handler {
return httptransport.NewHandler(
op,
DecodeOperationRequest,
EncodeOperationResponse,
EncodeOperationError,
httptransport.WithErrorHandler(errorHandler),
httptransport.WithOperationName("operation"),
)
}
Alternatively, the constructor function can instantiate the operation itself as well.
func NewOperationHandler(errorHandler httptransport.ErrorHandler) http.Handler {
return httptransport.NewHandler(
NewOperation(),
DecodeOperationRequest,
EncodeOperationResponse,
EncodeOperationError,
httptransport.WithErrorHandler(errorHandler),
httptransport.WithOperationName("operation"),
)
}
Register the HTTP handler in the router.