api

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

• Handler - Handlers are http handlers which understand backend protocols e.g rpc, http, web sockets
• Endpoint - Endpoints are used to create dynamic routes managed by the router
• Router - Router manages route mappings between endpoints and handlers

Endpoint

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: rpc.Handler,
})

// Run it as usual
service.Run()

Documentation

Index

• func Encode(e *Endpoint) map[string]string
• func Validate(e *Endpoint) error
• func WithEndpoint(e *Endpoint) server.HandlerOption
• type Endpoint
  • func Decode(e map[string]string) *Endpoint
• type Service

Functions

func Encode

func Encode(e *Endpoint) map[string]string

Encode encodes an endpoint to endpoint metadata

func Validate

func Validate(e *Endpoint) error

Validate validates an endpoint to guarantee it won't blow up when being served

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 string
	// 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

func Decode

func Decode(e map[string]string) *Endpoint

Decode decodes endpoint metadata into an endpoint

type Service

type Service struct {
	// Name of service
	Name string
	// The endpoint for this service
	Endpoint *Endpoint
	// Versions of this service
	Services []*registry.Service
}

Service represents an API service