rest

Documentation

Overview

Package rest of the Tideland Go REST Server Library provides types for the implementation of servers with a RESTful API. The business has to be implemented in types fullfilling the ResourceHandler interface. This basic interface only allows the initialization of the handler. More interesting are the other interfaces like GetResourceHandler which defines the Get() method for the HTTP request method GET. Others are for PUT, POST, HEAD, PATCH, DELETE, and OPTIONS. Their according methods get a Job as argument. It provides convenient helpers for the processing of the job.

type myHandler struct {
    id string
}

func NewMyHandler(id string) rest.ResourceHandler {
    return &myHandler{id}
}

func (h *myHandler) ID() string {
    return h.id
}

func (h *myHandler) Init(env rest.Environment, domain, resource string) error {
    // Nothing to do in this example.
    return nil
}

// Get handles reading of resources, here simplified w/o
// error handling.
func (h *myHandler) Get(job rest.Job) (bool, error) {
    id := job.ResourceID()
    if id == "" {
       all := model.GetAllData()
       job.JSON(true).Write(all)
       return true, nil
    }
    one := model.GetOneData(id)
    job.JSON(true).Write(one)
    return true, nil
}

The processing methods return two values: a boolean and an error. The latter is pretty clear, it signals a job processing error. The boolean is more interesting. Registering a handler is based on a domain and a resource. The URL

/<DOMAIN>/<RESOURCE>

leads to a handler, or even better, to a list of handlers. All are used as long as the returned boolean value is true. E.g. the first handler can check the authentication, the second one the authorization, and the third one does the business. Additionally the URL

/<DOMAIN>/<RESOURCE>/<ID>

provides the resource identifier via Job.ResourceID().

The handlers then are deployed to the Multiplexer which implements the Handler interface of the net/http package. So the typical order is

mux := rest.NewMultiplexer(ctx, cfg)

to start the multiplexer with a given context and the configuration for the multiplexer. The configuration is using the Tideland Go Library etc.Etc, parameters can be found at the NewMultiplexer documentation. After creating the multiplexer call

mux.Register("domain", "resource-type-a", NewTypeAHandler("foo"))
mux.Register("domain", "resource-type-b", NewTypeBHandler("bar"))
mux.Register("admin", "user", NewUserManagementHandler())

to register the handlers per domain and resource. The server then can be started by the standard

http.ListenAndServe(":8000", mux)

Additionally further handlers can be registered or running ones removed during the runtime.

Index

• Constants
• func NegativeFeedback(f Formatter, statusCode int, msg string, args ...interface{}) (bool, error)
• func PositiveFeedback(f Formatter, payload interface{}, msg string, args ...interface{}) (bool, error)
• type DeleteResourceHandler
• type Environment
  • func EnvironmentFromContext(ctx context.Context) (Environment, bool)
• type Feedback
• type Formatter
• type GetResourceHandler
• type HeadResourceHandler
• type Job
  • func JobFromContext(ctx context.Context) (Job, bool)
• type KeyValue
  • func (kv KeyValue) String() string
• type KeyValues
  • func (kvs KeyValues) String() string
• type Language
• type Languages
  • func (ls Languages) Len() int
  • func (ls Languages) Less(i, j int) bool
  • func (ls Languages) Swap(i, j int)
• type Multiplexer
  • func NewMultiplexer(ctx context.Context, cfg etc.Etc) Multiplexer
• type OptionsResourceHandler
• type PatchResourceHandler
• type PostResourceHandler
• type PutResourceHandler
• type Registration
• type Registrations
• type Renderer
• type ResourceHandler
• type TemplatesCache
• type Values

Constants

const (
	ErrDuplicateHandler = iota + 1
	ErrInitHandler
	ErrIllegalRequest
	ErrNoHandler
	ErrNoGetHandler
	ErrNoHeadHandler
	ErrNoPutHandler
	ErrNoPostHandler
	ErrNoPatchHandler
	ErrNoDeleteHandler
	ErrNoOptionsHandler
	ErrMethodNotSupported
	ErrUploadingFile
	ErrInvalidContentType
	ErrNoCachedTemplate
	ErrQueryValueNotFound
	ErrNoServerDefined
	ErrCannotPrepareRequest
	ErrHTTPRequestFailed
	ErrProcessingRequestContent
	ErrContentNotKeyValue
	ErrReadingResponse
)

Error codes of the rest package.

const (
	StatusOK                  = http.StatusOK
	StatusCreated             = http.StatusCreated
	StatusNoContent           = http.StatusNoContent
	StatusBadRequest          = http.StatusBadRequest
	StatusUnauthorized        = http.StatusUnauthorized
	StatusForbidden           = http.StatusForbidden
	StatusNotFound            = http.StatusNotFound
	StatusConflict            = http.StatusConflict
	StatusInternalServerError = http.StatusInternalServerError
)

Standard REST status codes.

const (
	ContentTypePlain      = "text/plain"
	ContentTypeHTML       = "text/html"
	ContentTypeXML        = "application/xml"
	ContentTypeJSON       = "application/json"
	ContentTypeGOB        = "application/vnd.tideland.gob"
	ContentTypeURLEncoded = "application/x-www-form-urlencoded"
)

Standard REST content types.

Functions

func NegativeFeedback

func NegativeFeedback(f Formatter, statusCode int, msg string, args ...interface{}) (bool, error)

NegativeFeedback writes a negative feedback envelope to the formatter. The message is also logged.

func PositiveFeedback

func PositiveFeedback(f Formatter, payload interface{}, msg string, args ...interface{}) (bool, error)

PositiveFeedback writes a positive feedback envelope to the formatter.

Types

type DeleteResourceHandler

type DeleteResourceHandler interface {
	Delete(job Job) (bool, error)
}

DeleteResourceHandler is the additional interface for handlers understanding the verb DELETE.

type Environment

type Environment interface {
	// Context returns the context of the environment.
	Context() context.Context

	// Basepath returns the configured basepath.
	Basepath() string

	// DefaultDomain returns the configured default domain.
	DefaultDomain() string

	// DefaultResource returns the configured default resource.
	DefaultResource() string

	// TemplatesCache returns the template cache.
	TemplatesCache() TemplatesCache
}

Environment describes the environment of a RESTful application.

func EnvironmentFromContext

func EnvironmentFromContext(ctx context.Context) (Environment, bool)

EnvironmentFromContext retrieves the environment out of a context.

type Feedback

type Feedback struct {
	StatusCode int         `json:"statusCode" xml:"statusCode"`
	Status     string      `json:"status" xml:"status"`
	Message    string      `json:"message,omitempty" xml:"message,omitempty"`
	Payload    interface{} `json:"payload,omitempty" xml:"payload,omitempty"`
}

Feedback is a helper to give a qualified feedback in RESTful requests. It contains wether the request has been successful, a message, and in case of success some payload if wanted.

type Formatter

type Formatter interface {
	// Write encodes the passed data to implementers format and writes
	// it with the passed status code and possible header values to the
	// response writer.
	Write(statusCode int, data interface{}, headers ...KeyValue) error

	// Read checks if the request content type matches the implementers
	// format, reads its body and decodes it to the value pointed to by
	// data.
	Read(data interface{}) error
}

Formatter allows reading or writing in handler methods based on the implementing formats like JSON, XML, or GOB.

type GetResourceHandler

type GetResourceHandler interface {
	Get(job Job) (bool, error)
}

GetResourceHandler is the additional interface for handlers understanding the verb GET.

type HeadResourceHandler

type HeadResourceHandler interface {
	Head(job Job) (bool, error)
}

HeadResourceHandler is the additional interface for handlers understanding the verb HEAD.

type Job

type Job interface {
	// Return the Job as string.
	fmt.Stringer

	// Environment returns the server environment.
	Environment() Environment

	// Request returns the used Go HTTP request.
	Request() *http.Request

	// ResponseWriter returns the used Go HTTP response writer.
	ResponseWriter() http.ResponseWriter

	// Domain returns the requests domain.
	Domain() string

	// Resource returns the requests resource.
	Resource() string

	// ResourceID return the requests resource ID.
	ResourceID() string

	// Context returns a job context also containing the
	// job itself.
	Context() context.Context

	// EnhanceContext allows to enhance the job context
	// values, a deadline, a timeout, or a cancel. So
	// e.g. a first handler in a handler queue can
	// store authentication information in the context
	// and a following handler can use it (see the
	// JWTAuthorizationHandler).
	EnhanceContext(func(ctx context.Context) context.Context)

	// Version returns the requested API version for this job. If none
	// is set the version 1.0.0 will be returned as default. It will
	// be retrieved aut of the header Version.
	Version() version.Version

	// SetVersion allows to set an API version for the response. If
	// none is set the version 1.0.0 will be set as default. It will
	// be set in the header Version.
	SetVersion(v version.Version)

	// AcceptsContentType checks if the requestor accepts a given content type.
	AcceptsContentType(contentType string) bool

	// HasContentType checks if the sent content has the given content type.
	HasContentType(contentType string) bool

	// Languages returns the accepted language with the quality values.
	Languages() Languages

	// InternalPath builds an internal path out of the passed parts.
	InternalPath(domain, resource, resourceID string, query ...KeyValue) string

	// Redirect to a domain, resource and resource ID (optional).
	Redirect(domain, resource, resourceID string)

	// Renderer returns a template renderer.
	Renderer() Renderer

	// GOB returns a GOB formatter.
	GOB() Formatter

	// JSON returns a JSON formatter.
	JSON(html bool) Formatter

	// XML returns a XML formatter.
	XML() Formatter

	// Query returns a convenient access to query values.
	Query() Values

	// Form returns a convenient access to form values.
	Form() Values
}

Job encapsulates all the needed information for handling a request.

func JobFromContext

func JobFromContext(ctx context.Context) (Job, bool)

JobFromContext retrieves the job out of a context.

type KeyValue

type KeyValue struct {
	Key   string
	Value interface{}
}

KeyValue assigns a value to a key.

func (KeyValue) String

func (kv KeyValue) String() string

String prints the encoded form key=value for URLs.

type KeyValues

type KeyValues []KeyValue

KeyValues is a number of key/value pairs.

func (KeyValues) String

func (kvs KeyValues) String() string

String prints the encoded form key=value joind by & for URLs.

type Language

type Language struct {
	Locale string
	Value  float64
}

Language is the valued language a request accepts as response.

type Languages

type Languages []Language

Languages is the ordered set of accepted languages.

func (Languages) Len

func (ls Languages) Len() int

Len returns the number of languages to fulfill the sort interface.

func (Languages) Less

func (ls Languages) Less(i, j int) bool

Less returns if the language with the index i has a smaller value than the one with index j to fulfill the sort interface.

func (Languages) Swap

func (ls Languages) Swap(i, j int)

Swap swaps the languages with the indexes i and j.

type Multiplexer

type Multiplexer interface {
	http.Handler

	// Register adds a resource handler for a given domain and resource.
	Register(domain, resource string, handler ResourceHandler) error

	// RegisterAll allows to register multiple handler in one run.
	RegisterAll(registrations Registrations) error

	// RegisteredHandlers returns the ID stack of registered handlers
	// for a domain and resource.
	RegisteredHandlers(domain, resource string) []string

	// Deregister removes one, more, or all resource handler for a
	// given domain and resource.
	Deregister(domain, resource string, ids ...string)
}

Multiplexer enhances the http.Handler interface by registration an deregistration of handlers.

func NewMultiplexer

func NewMultiplexer(ctx context.Context, cfg etc.Etc) Multiplexer

NewMultiplexer creates a new HTTP multiplexer. The passed context will be used if a handler requests a context from a job, the configuration allows to configure the multiplexer. The allowed parameters are

{etc
    {basepath /}
    {default-domain default}
    {default-resource default}
    {ignore-favicon true}
}

The values shown here are the default values if the configuration is nil or missing these settings.

type OptionsResourceHandler

type OptionsResourceHandler interface {
	Options(job Job) (bool, error)
}

OptionsResourceHandler is the additional interface for handlers understanding the verb OPTION.

type PatchResourceHandler

type PatchResourceHandler interface {
	Patch(job Job) (bool, error)
}

PatchResourceHandler is the additional interface for handlers understanding the verb PATCH.

type PostResourceHandler

type PostResourceHandler interface {
	Post(job Job) (bool, error)
}

PostResourceHandler is the additional interface for handlers understanding the verb POST.

type PutResourceHandler

type PutResourceHandler interface {
	Put(job Job) (bool, error)
}

PutResourceHandler is the additional interface for handlers understanding the verb PUT.

type Registration

type Registration struct {
	Domain   string
	Resource string
	Handler  ResourceHandler
}

Registration encapsulates one handler registration.

type Registrations

type Registrations []Registration

Registrations is a number handler registratons.

type Renderer

type Renderer interface {
	// Render executes the pre-parsed template with the data.
	// It also sets the content type header.
	Render(id string, data interface{}) error

	// LoadAndRender checks if the template with the given id
	// has already been parsed. In this case it will use it,
	// otherwise the template will be loaded, parsed, added
	// to the cache, and used then.
	LoadAndRender(id, filename, contentType string, data interface{}) error
}

Renderer renders templates. It is returned by a Job and knows where to render it.

type ResourceHandler

type ResourceHandler interface {
	// ID returns the deployment ID of the handler.
	ID() string

	// Init initializes the resource handler after registrations.
	Init(env Environment, domain, resource string) error
}

ResourceHandler is the base interface for all resource handlers understanding the REST verbs. It allows the initialization and returns an id that has to be unique for the combination of domain and resource. So it can later be removed again.

type TemplatesCache

type TemplatesCache interface {
	// Parse parses a raw template an stores it.
	Parse(id, rawTmpl, contentType string) error

	// LoadAndParse loads a template out of the filesystem,
	// parses and stores it.
	LoadAndParse(id, filename, contentType string) error

	// Render executes the pre-parsed template with the data.
	// It also sets the content type header.
	Render(rw http.ResponseWriter, id string, data interface{}) error

	// LoadAndRender checks if the template with the given id
	// has already been parsed. In this case it will use it,
	// otherwise the template will be loaded, parsed, added
	// to the cache, and used then.
	LoadAndRender(rw http.ResponseWriter, id, filename, contentType string, data interface{}) error
}

TemplatesCache caches and renders templates.

type Values

type Values interface {
	// ValueAsString retrieves the string value of a given key. If it
	// doesn't exist the default value dv is returned.
	ValueAsString(key, dv string) string

	// ValueAsBool retrieves the bool value of a given key. If it
	// doesn't exist the default value dv is returned.
	ValueAsBool(key string, dv bool) bool

	// ValueAsInt retrieves the int value of a given key. If it
	// doesn't exist the default value dv is returned.
	ValueAsInt(key string, dv int) int

	// ValueAsFloat64 retrieves the float64 value of a given key. If it
	// doesn't exist the default value dv is returned.
	ValueAsFloat64(key string, dv float64) float64

	// ValueAsTime retrieves the string value of a given key and
	// interprets it as time with the passed format. If it
	// doesn't exist the default value dv is returned.
	ValueAsTime(key, layout string, dv time.Time) time.Time

	// ValueAsDuration retrieves the duration value of a given key.
	// If it doesn't exist the default value dv is returned.
	ValueAsDuration(key string, dv time.Duration) time.Duration
}

Values allows typed access with default values to a jobs request values passed as query or form.