api

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 17, 2018 License: Apache-2.0 Imports: 5 Imported by: 1

README

Go API License GoDoc Travis CI Go Report Card

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 - The http handlers supported
  • Endpoints - Defining custom routes using endpoints

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 or application/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 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 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

func Decode

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

Decode decodes endpoint metadata into an 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"
)

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

Directories

Path Synopsis
Package handler provides http handlers
Package handler provides http handlers
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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL