rest

package
Version: v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 4, 2019 License: MIT Imports: 16 Imported by: 126

Documentation

Overview

Package rest is a `net/http` handler responsible for HTTP RESTful implementation for the REST Layer framework.

This package is part of the rest-layer project. See http://rest-layer.io for full REST Layer documentation.

Example
package main

import (
	"log"
	"net/http"
	"net/url"

	"github.com/rs/cors"
	"github.com/rs/rest-layer/resource"
	"github.com/rs/rest-layer/resource/testing/mem"
	"github.com/rs/rest-layer/rest"
	"github.com/rs/rest-layer/schema"
)

func main() {
	var (
		// Define a user resource schema
		user = schema.Schema{
			Fields: schema.Fields{
				"id": {
					Required: true,
					// When a field is read-only, on default values or hooks can
					// set their value. The client can't change it.
					ReadOnly: true,
					// This is a field hook called when a new user is created.
					// The schema.NewID hook is a provided hook to generate a
					// unique id when no value is provided.
					OnInit: schema.NewID,
					// The Filterable and Sortable allows usage of filter and sort
					// on this field in requests.
					Filterable: true,
					Sortable:   true,
					Validator: &schema.String{
						Regexp: "^[0-9a-f]{32}$",
					},
				},
				"created": {
					Required:   true,
					ReadOnly:   true,
					Filterable: true,
					Sortable:   true,
					OnInit:     schema.Now,
					Validator:  &schema.Time{},
				},
				"updated": {
					Required:   true,
					ReadOnly:   true,
					Filterable: true,
					Sortable:   true,
					OnInit:     schema.Now,
					// The OnUpdate hook is called when the item is edited. Here we use
					// provided Now hook which just return the current time.
					OnUpdate:  schema.Now,
					Validator: &schema.Time{},
				},
				// Define a name field as required with a string validator
				"name": {
					Required:   true,
					Filterable: true,
					Validator: &schema.String{
						MaxLen: 150,
					},
				},
			},
		}

		// Define a post resource schema
		post = schema.Schema{
			Fields: schema.Fields{
				// schema.*Field are shortcuts for common fields (identical to users' same fields)
				"id":      schema.IDField,
				"created": schema.CreatedField,
				"updated": schema.UpdatedField,
				// Define a user field which references the user owning the post.
				// See bellow, the content of this field is enforced by the fact
				// that posts is a sub-resource of users.
				"user": {
					Required:   true,
					Filterable: true,
					Validator: &schema.Reference{
						Path: "users",
					},
				},
				"public": {
					Filterable: true,
					Validator:  &schema.Bool{},
				},
				// Sub-documents are handled via a sub-schema
				"meta": {
					Schema: &schema.Schema{
						Fields: schema.Fields{
							"title": {
								Required: true,
								Validator: &schema.String{
									MaxLen: 150,
								},
							},
							"body": {
								Validator: &schema.String{
									MaxLen: 100000,
								},
							},
						},
					},
				},
			},
		}
	)

	// Create a REST API root resource
	index := resource.NewIndex()

	// Add a resource on /users[/:user_id]
	users := index.Bind("users", user, mem.NewHandler(), resource.Conf{
		// We allow all REST methods
		// (rest.ReadWrite is a shortcut for []rest.Mode{Create, Read, Update, Delete, List})
		AllowedModes: resource.ReadWrite,
	})

	// Bind a sub resource on /users/:user_id/posts[/:post_id]
	// and reference the user on each post using the "user" field of the posts resource.
	posts := users.Bind("posts", "user", post, mem.NewHandler(), resource.Conf{
		// Posts can only be read, created and deleted, not updated
		AllowedModes: []resource.Mode{resource.Read, resource.List, resource.Create, resource.Delete},
	})

	// Add a friendly alias to public posts
	// (equivalent to /users/:user_id/posts?filter={"public":true})
	posts.Alias("public", url.Values{"filter": []string{"{\"public\"=true}"}})

	// Create API HTTP handler for the resource graph
	api, err := rest.NewHandler(index)
	if err != nil {
		log.Fatalf("Invalid API configuration: %s", err)
	}

	// Add cors support
	h := cors.New(cors.Options{OptionsPassthrough: true}).Handler(api)

	// Bind the API under /api/ path
	http.Handle("/api/", http.StripPrefix("/api/", h))

	// Serve it
	log.Print("Serving API on http://localhost:8080")
	if err := http.ListenAndServe(":8080", nil); err != nil {
		log.Fatal(err)
	}
}
Output:

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound represents a 404 HTTP error.
	ErrNotFound = &Error{http.StatusNotFound, "Not Found", nil}
	// ErrForbidden represents a 403 HTTP error.
	ErrForbidden = &Error{http.StatusForbidden, "Forbidden", nil}
	// ErrPreconditionFailed happens when a conditional request condition is not met.
	ErrPreconditionFailed = &Error{http.StatusPreconditionFailed, "Precondition Failed", nil}
	// ErrConflict happens when another thread or node modified the data
	// concurrently with our own thread in such a way we can't securely apply
	// the requested changes.
	ErrConflict = &Error{http.StatusConflict, "Conflict", nil}
	// ErrInvalidMethod happens when the used HTTP method is not supported for
	// this resource.
	ErrInvalidMethod = &Error{http.StatusMethodNotAllowed, "Invalid Method", nil}
	// ErrClientClosedRequest is returned when the client closed the connection
	// before the server was able to finish processing the request.
	ErrClientClosedRequest = &Error{499, "Client Closed Request", nil}
	// ErrNotImplemented happens when a requested feature is not implemented.
	ErrNotImplemented = &Error{http.StatusNotImplemented, "Not Implemented", nil}
	// ErrGatewayTimeout is returned when the specified timeout for the request
	// has been reached before the server was able to process it.
	ErrGatewayTimeout = &Error{http.StatusGatewayTimeout, "Deadline Exceeded", nil}
	// ErrUnknown is thrown when the origin of the error can't be identified.
	ErrUnknown = &Error{520, "Unknown Error", nil}
)

Functions

func IndexFromContext

func IndexFromContext(ctx context.Context) (resource.Index, bool)

IndexFromContext extracts the router from the given net/context.

Types

type DefaultResponseFormatter

type DefaultResponseFormatter struct {
}

DefaultResponseFormatter provides a base response formatter to be used by default. This formatter can easily be extended or replaced by implementing ResponseFormatter interface and setting it on Handler.ResponseFormatter.

func (DefaultResponseFormatter) FormatError

func (f DefaultResponseFormatter) FormatError(ctx context.Context, headers http.Header, err error, skipBody bool) (context.Context, interface{})

FormatError implements ResponseFormatter.

func (DefaultResponseFormatter) FormatItem

func (f DefaultResponseFormatter) FormatItem(ctx context.Context, headers http.Header, i *resource.Item, skipBody bool) (context.Context, interface{})

FormatItem implements ResponseFormatter.

func (DefaultResponseFormatter) FormatList

func (f DefaultResponseFormatter) FormatList(ctx context.Context, headers http.Header, l *resource.ItemList, skipBody bool) (context.Context, interface{})

FormatList implements ResponseFormatter.

type DefaultResponseSender

type DefaultResponseSender struct {
}

DefaultResponseSender provides a base response sender to be used by default. This sender can easily be extended or replaced by implementing ResponseSender interface and setting it on Handler.ResponseSender.

func (DefaultResponseSender) Send

func (s DefaultResponseSender) Send(ctx context.Context, w http.ResponseWriter, status int, headers http.Header, body interface{})

Send sends headers with the given status and marshal the data in JSON.

type Error

type Error struct {
	// Code defines the error code to be used for the error and for the HTTP
	// status.
	Code int
	// Message is the error message.
	Message string
	// Issues holds per fields errors if any.
	Issues map[string][]interface{}
}

Error defines a REST error with optional per fields error details.

func NewError

func NewError(err error) *Error

NewError returns a rest.Error from an standard error.

If the the inputted error is recognized, the appropriate rest.Error is mapped.

func (*Error) Error

func (e *Error) Error() string

Error returns the error as string

type Handler

type Handler struct {
	// ResponseFormatter can be changed to extend the DefaultResponseFormatter.
	ResponseFormatter ResponseFormatter
	// ResponseSender can be changed to extend the DefaultResponseSender.
	ResponseSender ResponseSender
	// FallbackHandlerFunc is called when REST layer doesn't find a route for
	// the request. If not set, a 404 or 405 standard REST error is returned.
	FallbackHandlerFunc func(ctx context.Context, w http.ResponseWriter, r *http.Request)
	// contains filtered or unexported fields
}

Handler is a net/http compatible handler used to serve the configured REST API.

func NewHandler

func NewHandler(i resource.Index) (*Handler, error)

NewHandler creates an new REST API HTTP handler with the specified resource index.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles requests as a http.Handler.

func (*Handler) ServeHTTPC

func (h *Handler) ServeHTTPC(ctx context.Context, w http.ResponseWriter, r *http.Request)

ServeHTTPC handles requests as a xhandler.HandlerC (deprecated).

type ResourcePath

type ResourcePath []*ResourcePathComponent

ResourcePath is the list of ResourcePathComponent leading to the requested resource

func (ResourcePath) ParentsExist

func (p ResourcePath) ParentsExist(ctx context.Context) error

ParentsExist checks if the each intermediate parents in the path exist and return either a ErrNotFound or an error returned by on of the intermediate resource.

func (ResourcePath) Path

func (p ResourcePath) Path() string

Path returns the path to the resource to be used with resource.Root.GetResource.

func (*ResourcePath) Prepend

func (p *ResourcePath) Prepend(rsrc *resource.Resource, field string, value interface{})

Prepend add the given resource using the provided field and value as a "ghost" resource prefix to the resource path.

The effect will be a 404 error if the doesn't have an item with the id matching to the provided value.

This will also require that all subsequent resources in the path have this resource's "value" set on their "field" field.

Finally, all created resources at this path will also have this field and value set by default.

func (ResourcePath) Values

func (p ResourcePath) Values() map[string]interface{}

Values returns all the key=value pairs defined by the resource path.

type ResourcePathComponent

type ResourcePathComponent struct {
	// Name is the endpoint name used to bind the resource
	Name string
	// Field is the resource's field used to filter targeted resource
	Field string
	// Value holds the resource's id value
	Value interface{}
	// Resource references the resource
	Resource *resource.Resource
}

ResourcePathComponent represents the path of resource and sub-resources of a given request's resource

type ResponseFormatter

type ResponseFormatter interface {
	// FormatItem formats a single item in a format ready to be serialized by the ResponseSender
	FormatItem(ctx context.Context, headers http.Header, i *resource.Item, skipBody bool) (context.Context, interface{})
	// FormatList formats a list of items in a format ready to be serialized by the ResponseSender
	FormatList(ctx context.Context, headers http.Header, l *resource.ItemList, skipBody bool) (context.Context, interface{})
	// FormatError formats a REST formated error or a simple error in a format ready to be serialized by the ResponseSender
	FormatError(ctx context.Context, headers http.Header, err error, skipBody bool) (context.Context, interface{})
}

ResponseFormatter defines an interface responsible for formatting a the different types of response objects.

type ResponseSender

type ResponseSender interface {
	// Send serialize the body, sets the given headers and write everything to
	// the provided response writer.
	Send(ctx context.Context, w http.ResponseWriter, status int, headers http.Header, body interface{})
}

ResponseSender defines an interface responsible for serializing and sending the response to the http.ResponseWriter.

Example
package main

import (
	"context"
	"net/http"

	"github.com/rs/rest-layer/resource"
	"github.com/rs/rest-layer/rest"
)

type myResponseFormatter struct {
	// Extending default response sender
	rest.DefaultResponseFormatter
}

// Add a wrapper around the list with pagination info
func (r myResponseFormatter) FormatList(ctx context.Context, headers http.Header, l *resource.ItemList, skipBody bool) (context.Context, interface{}) {
	ctx, data := r.DefaultResponseFormatter.FormatList(ctx, headers, l, skipBody)
	return ctx, map[string]interface{}{
		"meta": map[string]int{
			"total":  l.Total,
			"offset": l.Offset,
		},
		"list": data,
	}
}

func main() {
	index := resource.NewIndex()
	api, _ := rest.NewHandler(index)
	api.ResponseFormatter = myResponseFormatter{}
}
Output:

type RouteMatch

type RouteMatch struct {
	// Method is the HTTP method used on the resource.
	Method string
	// ResourcePath is the list of intermediate resources followed by the
	// targeted resource. Each intermediate resource much match all the previous
	// resource components of this path and newly created resources will have
	// their corresponding fields filled with resource path information
	// (resource.field => resource.value).
	ResourcePath ResourcePath
	// Params is the list of client provided parameters (thru query-string or alias).
	Params url.Values
}

RouteMatch represent a REST request's matched resource with the method to apply and its parameters.

func FindRoute

func FindRoute(index resource.Index, req *http.Request) (*RouteMatch, error)

FindRoute returns the REST route for the given request.

func RouteFromContext

func RouteFromContext(ctx context.Context) (*RouteMatch, bool)

RouteFromContext extracts the matched route from the given net/context.

func (*RouteMatch) Query added in v0.2.0

func (r *RouteMatch) Query() (*query.Query, *Error)

Query builds a query object from the matched route

func (*RouteMatch) Release

func (r *RouteMatch) Release()

Release releases the route so it can be reused.

func (*RouteMatch) Resource

func (r *RouteMatch) Resource() *resource.Resource

Resource returns the last resource path's resource.

func (*RouteMatch) ResourceID

func (r *RouteMatch) ResourceID() interface{}

ResourceID returns the last resource path's resource id value if any.

If this method returns a non nil value, it means the route is an item request, otherwise it's a collection request.

Jump to

Keyboard shortcuts

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