File size: 2,254 Bytes
fea99b3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 | # 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.
```go
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.
```go
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.
```go
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.
```go
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.
```go
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.
|