rest

This example shows a minimal implementation of a ResourceHandler by using the BaseResourceHandler. It only implements an endpoint for fetching a resource.

package main

import "fmt"

// HelloWorldResource represents a domain model for which we want to perform
// CRUD operations with. Endpoints can operate on any type of entity --
// primitive, struct, or composite -- so long as it is serializable (by default,
// this means JSON-serializable via either MarshalJSON or JSON struct tags).
type HelloWorldResource struct {
	ID     int    `json:"id"`
	Foobar string `json:"foobar"`
}

// HelloWorldHandler implements the ResourceHandler interface. It specifies the
// business logic for performing CRUD operations. BaseResourceHandler provides
// stubs for each method if you only need to implement certain operations (as
// this example illustrates).
type HelloWorldHandler struct {
	BaseResourceHandler
}

// ResourceName is used to identify what resource a handler corresponds to and
// is used in the endpoint URLs, i.e. /api/:version/helloworld.
func (h HelloWorldHandler) ResourceName() string {
	return "helloworld"
}

// ReadResource is the logic that corresponds to reading a single resource by
// its ID at GET /api/:version/helloworld/{id}. Typically, this would make some
// sort of database query to load the resource. If the resource doesn't exist,
// nil should be returned along with an appropriate error.
func (h HelloWorldHandler) ReadResource(ctx RequestContext, id string,
	version string) (Resource, error) {
	// Make a database call here.
	if id == "42" {
		return &HelloWorldResource{ID: 42, Foobar: "hello world"}, nil
	}
	return nil, ResourceNotFound(fmt.Sprintf("No resource with id %s", id))
}

// This example shows a minimal implementation of a ResourceHandler by using the
// BaseResourceHandler. It only implements an endpoint for fetching a resource.
func main() {
	api := NewAPI(NewConfiguration())

	// Call RegisterResourceHandler to wire up HelloWorldHandler.
	api.RegisterResourceHandler(HelloWorldHandler{})

	// We're ready to hit our CRUD endpoints.
	api.Start(":8080")
}

Output:

This example shows how to implement a ResourceHandler which has an endpoint for fetching multiple resources and, optionally, retrieving only their IDs.

package main

import "strconv"

// MyResource represents a domain model for which we want to perform CRUD
// operations with. Endpoints can operate on any type of entity -- primitive,
// struct, or composite -- so long as it is serializable (by default, this means
// JSON-serializable via either MarshalJSON or JSON struct tags).
type MyResource struct {
	ID     int    `json:"id"`
	Foobar string `json:"foobar"`
}

// MyResourceHandler implements the ResourceHandler interface. It specifies the
// business logic for performing CRUD operations. BaseResourceHandler provides
// stubs for each method if you only need to implement certain operations (as
// this example illustrates).
type MyResourceHandler struct {
	BaseResourceHandler
}

// ResourceName is used to identify what resource a handler corresponds to and
// is used in the endpoint URLs, i.e. /api/:version/myresource.
func (m MyResourceHandler) ResourceName() string {
	return "myresource"
}

// ReadResourceList is the logic that corresponds to reading multiple resources,
// perhaps with specified query parameters accessed through the RequestContext.
// This is mapped to GET /api/:version/myresource. Typically, this would make
// some sort of database query to fetch the resources. It returns the slice of
// results, a cursor (or empty) string, and error (or nil). In this example, we
// illustrate how to use a query parameter to return only the IDs of our
// resources.
func (m MyResourceHandler) ReadResourceList(ctx RequestContext, limit int,
	cursor string, version string) ([]Resource, string, error) {
	// Make a database call here.
	resources := make([]Resource, 0, limit)
	resources = append(resources, &FooResource{ID: 1, Foobar: "hello"})
	resources = append(resources, &FooResource{ID: 2, Foobar: "world"})

	// ids_only is a query string parameter (i.e. /api/v1/myresource?ids_only=true).
	keysOnly, _ := strconv.ParseBool(ctx.ValueWithDefault("ids_only", "0").(string))

	if keysOnly {
		keys := make([]Resource, 0, len(resources))
		for _, resource := range resources {
			keys = append(keys, resource.(*FooResource).ID)
		}
		return keys, "", nil
	}

	return resources, "", nil
}

// This example shows how to implement a ResourceHandler which has an endpoint
// for fetching multiple resources and, optionally, retrieving only their IDs.
func main() {
	api := NewAPI(NewConfiguration())

	// Call RegisterResourceHandler to wire up HelloWorldHandler.
	api.RegisterResourceHandler(MyResourceHandler{})

	// We're ready to hit our CRUD endpoints.
	api.Start(":8080")
}

Output:

This example shows how to implement request middleware. ResourceHandlers provide the Authenticate method which is used to authenticate requests, but middleware allows you to insert additional authorization, logging, or other AOP-style operations.

package main

import (
	"errors"
	"fmt"
	"log"
	"net/http"
)

// MiddlewareResource represents a domain model for which we want to perform
// CRUD operations with. Endpoints can operate on any type of entity --
// primitive, struct, or composite -- so long as it is serializable (by default,
// this means JSON-serializable via either MarshalJSON or JSON struct tags).
type MiddlewareResource struct {
	ID     int    `json:"id"`
	Foobar string `json:"foobar"`
}

// MiddlewareHandler implements the ResourceHandler interface. It specifies the
// business logic for performing CRUD operations. BaseResourceHandler provides
// stubs for each method if you only need to implement certain operations (as
// this example illustrates).
type MiddlewareHandler struct {
	BaseResourceHandler
}

// ResourceName is used to identify what resource a handler corresponds to and
// is used in the endpoint URLs, i.e. /api/:version/example.
func (e MiddlewareHandler) ResourceName() string {
	return "example"
}

// Authenticate is logic that is used to authenticate requests to this
// ResourceHandler. Returns nil if the request is authenticated or an error if
// it is not.
func (e MiddlewareHandler) Authenticate(r *http.Request) error {
	if r.Header.Get("Answer") != "42" {
		return errors.New("what is the answer?")
	}
	return nil
}

// ReadResource is the logic that corresponds to reading a single resource by
// its ID at GET /api/:version/example/{id}. Typically, this would make some
// sort of database query to load the resource. If the resource doesn't exist,
// nil should be returned along with an appropriate error.
func (e MiddlewareHandler) ReadResource(ctx RequestContext, id string, version string) (Resource, error) {
	// Make a database call here.
	if id == "42" {
		return &MiddlewareResource{ID: 42, Foobar: "hello world"}, nil
	}
	return nil, ResourceNotFound(fmt.Sprintf("No resource with id %s", id))
}

// ResourceHandler middleware is implemented as a closure which takes an
// http.Handler and returns one.
func HandlerMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		log.Printf("Request: %s", r.URL.String())
		next.ServeHTTP(w, r)
	})
}

// Global API middleware is implemented as a function which takes an
// http.ResponseWriter and http.Request and returns a MiddlewareError if the
// request should terminate.
func GlobalMiddleware(w http.ResponseWriter, r *http.Request) *MiddlewareError {
	log.Println(r)
	return nil
}

// This example shows how to implement request middleware. ResourceHandlers
// provide the Authenticate method which is used to authenticate requests, but
// middleware allows you to insert additional authorization, logging, or other
// AOP-style operations.
func main() {
	api := NewAPI(NewConfiguration())

	// Call RegisterResourceHandler to wire up MiddlewareHandler and apply middleware.
	api.RegisterResourceHandler(MiddlewareHandler{}, HandlerMiddleware)

	// Middleware provided to Start and StartTLS are invoked for every request handled
	// by the API.
	api.Start(":8080", GlobalMiddleware)
}

Output:

This example shows how to implement a custom ResponseSerializer. The format responses are sent in is specified by the "format" query string parameter. By default, json is the only available format, but the ResponseSerializer interface allows different formats to be implemented.

package main

import "gopkg.in/yaml.v1"

// YAMLSerializer implements the ResponseSerializer interface.
type YAMLSerializer struct{}

// Serialize marshals a response payload into a byte slice to be sent over the
// wire.
func (y YAMLSerializer) Serialize(p Payload) ([]byte, error) {
	return yaml.Marshal(p)
}

// ContentType returns the MIME type of the response.
func (y YAMLSerializer) ContentType() string {
	return "text/yaml"
}

// This example shows how to implement a custom ResponseSerializer. The format
// responses are sent in is specified by the "format" query string parameter. By
// default, json is the only available format, but the ResponseSerializer
// interface allows different formats to be implemented.
func main() {
	api := NewAPI(NewConfiguration())

	// Call RegisterResponseSerializer to wire up YAMLSerializer.
	api.RegisterResponseSerializer("yaml", YAMLSerializer{})

	// Call RegisterResourceHandler to wire up HelloWorldHandler.
	api.RegisterResourceHandler(HelloWorldHandler{})

	// We're ready to hit our CRUD endpoints. Use ?format=yaml to get responses as YAML.
	api.Start(":8080")
}

Output:

This example shows how Rules are used to provide fine-grained control over response input and output.

package main

import (
	"fmt"
	"math/rand"
)

// ResourceWithSecret represents a domain model for which we want to perform
// CRUD operations with. Endpoints can operate on any type of entity --
// primitive, struct, or composite -- so long as it is serializable (by default,
// this means JSON-serializable via either MarshalJSON or JSON struct tags). The
// resource in this example has a field, "Secret", which we don't want to
// include in REST responses.
type ResourceWithSecret struct {
	ID     int
	Foo    string
	Nested FooResource
	Secret string
}

// ResourceWithSecretHandler implements the ResourceHandler interface. It
// specifies the business logic for performing CRUD operations.
// BaseResourceHandler provides stubs for each method if you only need to
// implement certain operations (as this example illustrates).
type ResourceWithSecretHandler struct {
	BaseResourceHandler
}

// ResourceName is used to identify what resource a handler corresponds to and
// is used in the endpoint URLs, i.e. /api/:version/resource.
func (r ResourceWithSecretHandler) ResourceName() string {
	return "resource"
}

// CreateResource is the logic that corresponds to creating a new resource at
// POST /api/:version/resource. Typically, this would insert a record into a
// database. It returns the newly created resource or an error if the create
// failed. Because our Rules specify types, we can access the Payload data in a
// type-safe way.
func (r ResourceWithSecretHandler) CreateResource(ctx RequestContext, data Payload,
	version string) (Resource, error) {
	// Make a database call here.
	id := rand.Int()
	foo, _ := data.GetString("foo")
	created := &ResourceWithSecret{ID: id, Foo: foo, Secret: "secret"}
	return created, nil
}

// ReadResource is the logic that corresponds to reading a single resource by
// its ID at GET /api/:version/resource/{id}. Typically, this would make some
// sort of database query to load the resource. If the resource doesn't exist,
// nil should be returned along with an appropriate error.
func (r ResourceWithSecretHandler) ReadResource(ctx RequestContext, id string,
	version string) (Resource, error) {
	// Make a database call here.
	if id == "42" {
		return &ResourceWithSecret{
			ID:     42,
			Foo:    "hello world",
			Secret: "keep it secret, keep it safe",
		}, nil
	}
	return nil, ResourceNotFound(fmt.Sprintf("No resource with id %s", id))
}

// Rules returns the resource rules to apply to incoming requests and outgoing
// responses. The default behavior, seen in BaseResourceHandler, is to apply no
// rules. Note that a Rule is not specified for the "Secret" field. This means
// that field will not be included in the response. The "Type" field on a Rule
// indicates the type the incoming data should be coerced to. If coercion fails,
// an error indicating this will be sent back in the response. If no type is
// specified, no coercion will be performed. Rules may also be nested. NewRules
// is used to initialize Rules and associate them with the resource type using
// the nil pointer. This allows Rule validation to occur at startup.
func (r ResourceWithSecretHandler) Rules() Rules {
	return NewRules((*ResourceWithSecret)(nil),
		&Rule{
			Field:      "ID",
			FieldAlias: "id",
			Type:       Int,
			Versions:   []string{"1, 2"},
			OutputOnly: true,
		},
		&Rule{
			Field:      "Foo",
			FieldAlias: "f",
			Type:       String,
			Versions:   []string{"1"},
			Required:   true,
		},
		&Rule{
			Field:      "Foo",
			FieldAlias: "foo",
			Type:       String,
			Versions:   []string{"2"},
			Required:   true,
		},
		&Rule{
			Field:      "Nested",
			FieldAlias: "nested",
			Versions:   []string{"2"},
			Rules: NewRules((*FooResource)(nil),
				&Rule{
					Field:      "ID",
					FieldAlias: "id",
					Type:       Int,
					OutputOnly: true,
				},
				&Rule{
					Field:      "Foobar",
					FieldAlias: "foobar",
					Type:       String,
				},
			),
		},
	)
}

// This example shows how Rules are used to provide fine-grained control over
// response input and output.
func main() {
	api := NewAPI(NewConfiguration())

	// Call RegisterResourceHandler to wire up ResourceWithSecretHandler.
	api.RegisterResourceHandler(ResourceWithSecretHandler{})

	// We're ready to hit our CRUD endpoints.
	api.Start(":8080")
}

Output:

This example shows how to fully implement a basic ResourceHandler for performing CRUD operations.

package main

import (
	"fmt"
	"math/rand"
	"net/http"
	"strconv"
)

// FooResource represents a domain model for which we want to perform CRUD
// operations with. Endpoints can operate on any type of entity -- primitive,
// struct, or composite -- so long as it is serializable (by default, this means
// JSON-serializable via either MarshalJSON or JSON struct tags).
type FooResource struct {
	ID     int    `json:"id"`
	Foobar string `json:"foobar"`
}

// FooHandler implements the ResourceHandler interface. It specifies the
// business logic for performing CRUD operations.
type FooHandler struct {
	BaseResourceHandler
}

// ResourceName is used to identify what resource a handler corresponds to and
// is used in the endpoint URLs, i.e. /api/:version/foo.
func (f FooHandler) ResourceName() string {
	return "foo"
}

// CreateResource is the logic that corresponds to creating a new resource at
// POST /api/:version/foo. Typically, this would insert a record into a
// database. It returns the newly created resource or an error if the create
// failed.
func (f FooHandler) CreateResource(ctx RequestContext, data Payload,
	version string) (Resource, error) {
	// Make a database call here.
	id := rand.Int()
	foobar, _ := data.GetString("foobar")
	created := &FooResource{ID: id, Foobar: foobar}
	return created, nil
}

// ReadResource is the logic that corresponds to reading a single resource by
// its ID at GET /api/:version/foo/{id}. Typically, this would make some sort of
// database query to load the resource. If the resource doesn't exist, nil
// should be returned along with an appropriate error.
func (f FooHandler) ReadResource(ctx RequestContext, id string,
	version string) (Resource, error) {
	// Make a database call here.
	if id == "42" {
		return &FooResource{ID: 42, Foobar: "hello world"}, nil
	}
	return nil, ResourceNotFound(fmt.Sprintf("No resource with id %s", id))
}

// ReadResourceList is the logic that corresponds to reading multiple resources,
// perhaps with specified query parameters accessed through the RequestContext.
// This is mapped to GET /api/:version/foo. Typically, this would make some sort
// of database query to fetch the resources. It returns the slice of results, a
// cursor (or empty) string, and error (or nil).
func (f FooHandler) ReadResourceList(ctx RequestContext, limit int,
	cursor string, version string) ([]Resource, string, error) {
	// Make a database call here.
	resources := make([]Resource, 0, limit)
	resources = append(resources, &FooResource{ID: 1, Foobar: "hello"})
	resources = append(resources, &FooResource{ID: 2, Foobar: "world"})
	return resources, "", nil
}

// UpdateResource is the logic that corresponds to updating an existing resource
// at PUT /api/:version/foo/{id}. Typically, this would make some sort of
// database update call. It returns the updated resource or an error if the
// update failed.
func (f FooHandler) UpdateResource(ctx RequestContext, id string, data Payload,
	version string) (Resource, error) {
	// Make a database call here.
	updateID, _ := strconv.Atoi(id)
	foobar, _ := data.GetString("foobar")
	foo := &FooResource{ID: updateID, Foobar: foobar}
	return foo, nil
}

// DeleteResource is the logic that corresponds to deleting an existing resource
// at DELETE /api/:version/foo/{id}. Typically, this would make some sort of
// database delete call. It returns the deleted resource or an error if the
// delete failed.
func (f FooHandler) DeleteResource(ctx RequestContext, id string,
	version string) (Resource, error) {
	// Make a database call here.
	deleteID, _ := strconv.Atoi(id)
	foo := &FooResource{ID: deleteID, Foobar: "Goodbye world"}
	return foo, nil
}

// Authenticate is logic that is used to authenticate requests. The default
// behavior of Authenticate, seen in BaseResourceHandler, always returns nil,
// meaning all requests are authenticated. Returning an error means that the
// request is unauthorized and any error message will be sent back with the
// response.
func (f FooHandler) Authenticate(r *http.Request) error {
	if secrets, ok := r.Header["Authorization"]; ok {
		if secrets[0] == "secret" {
			return nil
		}
	}

	return UnauthorizedRequest("You shall not pass")
}

// This example shows how to fully implement a basic ResourceHandler for
// performing CRUD operations.
func main() {
	api := NewAPI(NewConfiguration())

	// Call RegisterResourceHandler to wire up FooHandler.
	api.RegisterResourceHandler(FooHandler{})

	// We're ready to hit our CRUD endpoints.
	api.Start(":8080")
}

Output: