Documentation ¶
Overview ¶
Package jshapi is a http.Handler compatible wrapper that makes building JSON API resource handlers easy.
Index ¶
- Variables
- type API
- type MockStorage
- func (m *MockStorage) Delete(ctx context.Context, id string) jsh.ErrorType
- func (m *MockStorage) Get(ctx context.Context, id string) (*jsh.Object, jsh.ErrorType)
- func (m *MockStorage) List(ctx context.Context) (jsh.List, jsh.ErrorType)
- func (m *MockStorage) SampleList(length int) jsh.List
- func (m *MockStorage) SampleObject(id string) *jsh.Object
- func (m *MockStorage) Save(ctx context.Context, object *jsh.Object) (*jsh.Object, jsh.ErrorType)
- func (m *MockStorage) Update(ctx context.Context, object *jsh.Object) (*jsh.Object, jsh.ErrorType)
- type Relationship
- type Resource
- func (res *Resource) Action(actionName string, storage store.Get)
- func (res *Resource) CRUD(storage store.CRUD)
- func (res *Resource) Delete(storage store.Delete)
- func (res *Resource) Get(storage store.Get)
- func (res *Resource) List(storage store.List)
- func (res *Resource) Patch(storage store.Update)
- func (res *Resource) Post(storage store.Save)
- func (res *Resource) RouteTree() string
- func (res *Resource) ToMany(resourceType string, storage store.ToMany)
- func (res *Resource) ToOne(resourceType string, storage store.Get)
- type Sender
Constants ¶
This section is empty.
Variables ¶
var SendHandler = DefaultSender(log.New(os.Stderr, "jshapi: ", log.LstdFlags))
SendHandler allows the customization of how API responses are sent and logged. This is used by all jshapi.Resource objects.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct { *goji.Mux Resources map[string]*Resource Debug bool // contains filtered or unexported fields }
API is used to direct HTTP requests to resources
func Default ¶
Default builds a new top-level API with a few out of the box additions to get people started without needing to add a lot of extra functionality.
The most basic implementation is:
// create a logger, the std log package works, as do most other loggers // std.Logger interface defined here: // https://github.com/derekdowling/go-stdlogger/blob/master/logger.go logger := log.New(os.Stderr, "jshapi: ", log.LstdFlags) // create the API. Specify a http://yourapi/<prefix>/ if required api := jshapi.Default("<prefix>", false, logger) api.Add(yourResource)
type MockStorage ¶
type MockStorage struct { // ResourceType is the name of the resource you are mocking i.e. "user", "comment" ResourceType string // ResourceAttributes a sample set of attributes a resource object should have // used by GET /resources and GET /resources/:id ResourceAttributes interface{} // ListCount is the number of sample objects to return in a GET /resources request ListCount int }
MockStorage allows you to mock out APIs really easily, and is also used internally for testing the API layer.
func (*MockStorage) Delete ¶
func (m *MockStorage) Delete(ctx context.Context, id string) jsh.ErrorType
Delete does nothing
func (*MockStorage) Get ¶
func (m *MockStorage) Get(ctx context.Context, id string) (*jsh.Object, jsh.ErrorType)
Get returns a resource with ID as specified by the request
func (*MockStorage) List ¶
func (m *MockStorage) List(ctx context.Context) (jsh.List, jsh.ErrorType)
List returns a sample list
func (*MockStorage) SampleList ¶
func (m *MockStorage) SampleList(length int) jsh.List
SampleList generates a sample list of resources that can be used for/against the mock API
func (*MockStorage) SampleObject ¶
func (m *MockStorage) SampleObject(id string) *jsh.Object
SampleObject builds an object based on provided resource specifications
func (*MockStorage) Save ¶
func (m *MockStorage) Save(ctx context.Context, object *jsh.Object) (*jsh.Object, jsh.ErrorType)
Save assigns a URL of 1 to the object
func (*MockStorage) Update ¶
func (m *MockStorage) Update(ctx context.Context, object *jsh.Object) (*jsh.Object, jsh.ErrorType)
Update does nothing
type Relationship ¶
type Relationship string
Relationship helps define the relationship between two resources
const ( // ToOne signifies a one to one relationship ToOne Relationship = "One-To-One" // ToMany signifies a one to many relationship ToMany Relationship = "One-To-Many" )
type Resource ¶
type Resource struct { *goji.Mux // The singular name of the resource type("user", "post", etc) Type string // Routes is a list of routes registered to the resource Routes []string // Map of relationships Relationships map[string]Relationship }
Resource holds the necessary state for creating a REST API endpoint for a given resource type. Will be accessible via `/<type>`.
Using NewCRUDResource you can generate a generic CRUD handler for a JSON Specification Resource end point. If you wish to only implement a subset of these endpoints that is also available through NewResource() and manually registering storage handlers via .Post(), .Get(), .List(), .Patch(), and .Delete():
Besides the built in registration helpers, it isn't recommended, but you can add your own routes using the goji.Mux API:
func searchHandler(ctx context.Context, w http.ResponseWriter, r *http.Request) { name := pat.Param(ctx, "name") fmt.Fprintf(w, "Hello, %s!", name) } resource := jshapi.NewCRUDResource("users", userStorage) // creates /users/search/:name resource.HandleC(pat.New("search/:name"), searchHandler)
func NewCRUDResource ¶
NewCRUDResource generates a resource
func NewMockResource ¶
NewMockResource builds a mock API endpoint that can perform basic CRUD actions:
GET /types POST /types GET /types/:id DELETE /types/:id PATCH /types/:id
Will return objects and lists based upon the sampleObject that is specified here in the constructor.
func NewResource ¶
NewResource is a resource constructor that makes no assumptions about routes that you'd like to implement, but still provides some basic utilities for managing routes and handling API calls.
The prefix parameter causes all routes created within the resource to be prefixed.
func (*Resource) Action ¶
Action allows you to add custom actions to your resource types, it uses the GET /(prefix/)resourceTypes/:id/<actionName> path format
func (*Resource) CRUD ¶
CRUD is syntactic sugar and a shortcut for registering all JSON API CRUD routes for a compatible storage implementation:
Registers handlers for:
GET /resource POST /resource GET /resource/:id DELETE /resource/:id PATCH /resource/:id
func (*Resource) RouteTree ¶
RouteTree prints a recursive route tree based on what the resource, and all subresources have registered
func (*Resource) ToMany ¶
ToMany registers a `GET /resource/:id/(relationships/)<resourceType>s` route which returns a list of "resourceType"s in a One-To-Many relationship with the parent resource. The "/relationships/" uri component is optional.
CRUD actions on a specific relationship "resourceType" object should be performed via it's own top level /<resourceType> jsh-api handler as per JSONAPI specification.
func (*Resource) ToOne ¶
ToOne registers a `GET /resource/:id/(relationships/)<resourceType>` route which returns a "resourceType" in a One-To-One relationship between the parent resource type and "resourceType" as specified here. The "/relationships/" uri component is optional.
CRUD actions on a specific relationship "resourceType" object should be performed via it's own top level /<resourceType> jsh-api handler as per JSONAPI specification.
type Sender ¶
Sender is a function type definition that allows consumers to customize how they send and log API responses.
func DefaultSender ¶
func DefaultSender(logger std.Logger) Sender
DefaultSender is the default sender that will log 5XX errors that it encounters in the process of sending a response.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Godeps
|
|
_workspace/src/github.com/asaskevich/govalidator
Package govalidator is package of validators and sanitizers for strings, structs and collections.
|
Package govalidator is package of validators and sanitizers for strings, structs and collections. |
_workspace/src/github.com/derekdowling/go-json-spec-handler
Package jsh (JSON API Specification Handler) makes it easy to parse JSON API requests and send responses that match the JSON API Specification: http://jsonapi.org/ from your server.
|
Package jsh (JSON API Specification Handler) makes it easy to parse JSON API requests and send responses that match the JSON API Specification: http://jsonapi.org/ from your server. |
_workspace/src/github.com/derekdowling/go-json-spec-handler/client
Package jsc (JSON Specification Client) is an http client that makes sending HTTP requests that match the JSON Specification: http://jsonapi.org/ simple.
|
Package jsc (JSON Specification Client) is an http client that makes sending HTTP requests that match the JSON Specification: http://jsonapi.org/ simple. |
_workspace/src/github.com/derekdowling/go-stdlogger
Package std is the missing standard logging interface that should be present within Go.
|
Package std is the missing standard logging interface that should be present within Go. |
_workspace/src/github.com/jtolds/gls
Package gls implements goroutine-local storage.
|
Package gls implements goroutine-local storage. |
_workspace/src/github.com/smartystreets/assertions
Package assertions contains the implementations for all assertions which are referenced in goconvey's `convey` package (github.com/smartystreets/goconvey/convey) for use with the So(...) method.
|
Package assertions contains the implementations for all assertions which are referenced in goconvey's `convey` package (github.com/smartystreets/goconvey/convey) for use with the So(...) method. |
_workspace/src/github.com/smartystreets/assertions/internal/oglematchers
Package oglematchers provides a set of matchers useful in a testing or mocking framework.
|
Package oglematchers provides a set of matchers useful in a testing or mocking framework. |
_workspace/src/github.com/smartystreets/assertions/internal/oglemock/createmock
createmock is used to generate source code for mock versions of interfaces from installed packages.
|
createmock is used to generate source code for mock versions of interfaces from installed packages. |
_workspace/src/github.com/smartystreets/assertions/internal/oglemock/generate
Package generate implements code generation for mock classes.
|
Package generate implements code generation for mock classes. |
_workspace/src/github.com/smartystreets/assertions/internal/oglemock/generate/test_cases/complicated_pkg
Package complicated_pkg contains an interface with lots of interesting cases, for use in integration testing.
|
Package complicated_pkg contains an interface with lots of interesting cases, for use in integration testing. |
_workspace/src/github.com/smartystreets/assertions/internal/oglemock/generate/test_cases/renamed_pkg
A package that calls itself something different than its package path would have you believe.
|
A package that calls itself something different than its package path would have you believe. |
_workspace/src/github.com/smartystreets/assertions/internal/ogletest
Package ogletest provides a framework for writing expressive unit tests.
|
Package ogletest provides a framework for writing expressive unit tests. |
_workspace/src/github.com/smartystreets/assertions/internal/ogletest/srcutil
Functions for working with source code.
|
Functions for working with source code. |
_workspace/src/github.com/smartystreets/assertions/internal/reqtrace
Package reqtrace contains a very simple request tracing framework.
|
Package reqtrace contains a very simple request tracing framework. |
_workspace/src/github.com/smartystreets/assertions/should
package should is simply a rewording of the assertion functions in the assertions package.
|
package should is simply a rewording of the assertion functions in the assertions package. |
_workspace/src/github.com/smartystreets/goconvey/convey
Package convey contains all of the public-facing entry points to this project.
|
Package convey contains all of the public-facing entry points to this project. |
_workspace/src/github.com/smartystreets/goconvey/convey/gotest
Package gotest contains internal functionality.
|
Package gotest contains internal functionality. |
_workspace/src/github.com/smartystreets/goconvey/convey/reporting
Package reporting contains internal functionality related to console reporting and output.
|
Package reporting contains internal functionality related to console reporting and output. |
_workspace/src/github.com/zenazn/goji/web/mutil
Package mutil contains various functions that are helpful when writing http middleware.
|
Package mutil contains various functions that are helpful when writing http middleware. |
_workspace/src/goji.io
Package goji is a minimalistic and flexible HTTP request multiplexer.
|
Package goji is a minimalistic and flexible HTTP request multiplexer. |
_workspace/src/goji.io/internal
Package internal is a private package that allows Goji to expose a less confusing interface to its users.
|
Package internal is a private package that allows Goji to expose a less confusing interface to its users. |
_workspace/src/goji.io/middleware
Package middleware contains utilities for Goji Middleware authors.
|
Package middleware contains utilities for Goji Middleware authors. |
_workspace/src/goji.io/pat
Package pat is a URL-matching domain-specific language for Goji.
|
Package pat is a URL-matching domain-specific language for Goji. |
_workspace/src/goji.io/pattern
Package pattern contains utilities for Goji Pattern authors.
|
Package pattern contains utilities for Goji Pattern authors. |
_workspace/src/golang.org/x/net/context
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.
|
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes. |
_workspace/src/golang.org/x/net/context/ctxhttp
Package ctxhttp provides helper functions for performing context-aware HTTP requests.
|
Package ctxhttp provides helper functions for performing context-aware HTTP requests. |
Package store is a collection of composable interfaces that are can be implemented in order to build a storage driver
|
Package store is a collection of composable interfaces that are can be implemented in order to build a storage driver |