README
¶
Go API

Go API is a pluggable API framework
It builds on go-micro and includes a set of packages for composing HTTP based APIs
Note: This is a WIP
Getting Started
Handlers
Handlers are HTTP handlers which provide a single entry point and act as a gateway to backend services. Handlers manage dynamic routing from a http request to unique microservices.
Current handlers implemented
api
- Handles any HTTP request. Gives full control over the http request/response via RPC.event
- Handles any HTTP request and publishes to a message bus.http
- Handles any HTTP request and forwards as a reverse proxy.rpc
- Handles json and protobuf POST requests. Forwards as RPC.web
- The HTTP handler with web socket support included.
API Handler
The API handler is the default handler. It serves any HTTP requests and forwards on as an RPC request with a specific format.
- Content-Type: Any
- Body: Any
- Forward Format: api.Request/api.Response
- Path:
/[service]/[method]
- Resolver: Path is used to resolve service and method
Event Handler
The event handler serves HTTP and forwards the request as a message over a message bus using the go-micro broker.
- Content-Type: Any
- Body: Any
- Forward Format: Request is formatted as go-api/proto.Event
- Path:
/[topic]/[event]
- Resolver: Path is used to resolve topic and event name
HTTP Handler
The http handler is a http reserve proxy with built in service discovery.
- Content-Type: Any
- Body: Any
- Forward Format: HTTP Reverse proxy
- Path:
/[service]
- Resolver: Path is used to resolve service name
RPC Handler
The RPC handler serves json or protobuf HTTP POST requests and forwards as an RPC request.
- Content-Type:
application/json
orapplication/protobuf
- Body: JSON or Protobuf
- Forward Format: json-rpc or proto-rpc based on content
- Path:
/[service]/[method]
- Resolver: Path is used to resolve service and method
Web Handler
The web handler is a http reserve proxy with built in service discovery and web socket support.
- Content-Type: Any
- Body: Any
- Forward Format: HTTP Reverse proxy including web sockets
- Path:
/[service]
- Resolver: Path is used to resolve service name
Endpoints
Endpoints allow a service to dynamically configure the micro api handler
When defining your service also include the endpoint mapping
Example
This example serves /greeter
with http methods GET and POST to the Greeter.Hello RPC handler.
type Greeter struct
// Define the handler
func (g *Greeter) Hello(ctx context.Context, req *proto.Request, rsp *proto.Response) error {
log.Print("Received Greeter.Hello API request")
// make the request
response, err := g.Client.Hello(ctx, &hello.Request{Name: req.Name})
if err != nil {
return err
}
// set api response
rsp.Msg = response.Msg
return nil
}
// A greeter service
service := micro.NewService(
micro.Name("go.micro.api.greeter"),
)
// Parse command line flags
service.Init()
// Register handler and the endpoint mapping
proto.RegisterGreeterHandler(service.Server(), new(Greeter), api.WithEndpoint(&api.Endpoint{
// The RPC method
Name: "Greeter.Hello",
// The HTTP paths. This can be a POSIX regex
Path: []string{"/greeter"},
// The HTTP Methods for this endpoint
Method: []string{"GET", "POST"},
// The API handler to use
Handler: api.Rpc,
})
// Run it as usual
service.Run()
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithEndpoint ¶
func WithEndpoint(e *Endpoint) server.HandlerOption
WithEndpoint returns a server.HandlerOption with endpoint metadata set usage: proto.Register(server, handler, api.WithEndpoint(&Endpoint{Name: "Greeter.Hello", Path: []string{"/greeter"}}))
Types ¶
type Endpoint ¶
type Endpoint struct { // RPC Method e.g. Greeter.Hello Name string // Description e.g what's this endpoint for Description string // API Handler e.g rpc, proxy Handler Handler // HTTP Host e.g example.com Host []string // HTTP Methods e.g GET, POST Method []string // HTTP Path e.g /greeter. Expect POSIX regex Path []string }
Endpoint is a mapping between an RPC method and HTTP endpoint
type Handler ¶
type Handler string
Handler defines the type of handler uses by the micro api
const ( // Default defines the default handler Default Handler = "meta" // serves api.Request and api.Response Api Handler = "api" // serves the async api.Event handler Event Handler = "event" // forwards as http request Http Handler = "http" // proxies a http request Proxy Handler = "proxy" // services an RPC request/response Rpc Handler = "rpc" // serves the web proxy handler Web Handler = "web" )
Directories
¶
Path | Synopsis |
---|---|
Package handler provides http handlers
|
Package handler provides http handlers |
web
Package web contains the web handler including websocket support
|
Package web contains the web handler including websocket support |
internal
|
|
Package go_api is a generated protocol buffer package.
|
Package go_api is a generated protocol buffer package. |
Package router provides api service routing
|
Package router provides api service routing |
Package server provides a http server with features; acme, cors, etc
|
Package server provides a http server with features; acme, cors, etc |