jsonapi

README

Neuron json:api - HTTP Server

This repository contains Neuron extension for the HTTP Server, that implements json:api specification.

Documentation

Index

• func MidAccept(next http.Handler) http.Handler
• func MidContentType(next http.Handler) http.Handler
• type API
  • func New(options ...Option) *API
  • func (a *API) GetEndpoints() []*server.Endpoint
  • func (a *API) HandleDelete(model mapping.Model) http.HandlerFunc
  • func (a *API) HandleDeleteRelationship(model mapping.Model, relationName string) http.HandlerFunc
  • func (a *API) HandleGet(model mapping.Model) http.HandlerFunc
  • func (a *API) HandleGetRelated(model mapping.Model, relationName string) http.HandlerFunc
  • func (a *API) HandleGetRelationship(model mapping.Model, relationName string) http.HandlerFunc
  • func (a *API) HandleInsert(model mapping.Model) http.HandlerFunc
  • func (a *API) HandleInsertRelationship(model mapping.Model, relationName string) http.HandlerFunc
  • func (a *API) HandleList(model mapping.Model) http.HandlerFunc
  • func (a *API) HandleUpdate(model mapping.Model) http.HandlerFunc
  • func (a *API) HandleUpdateRelationship(model mapping.Model, relationName string) http.HandlerFunc
  • func (a *API) InitializeAPI(c *core.Controller) error
  • func (a *API) SetRoutes(router *httprouter.Router) error
• type DefaultHandler
  • func (d *DefaultHandler) HandleDelete(ctx context.Context, db database.DB, q *query.Scope) (*codec.Payload, error)
  • func (d *DefaultHandler) HandleGet(ctx context.Context, db database.DB, q *query.Scope) (*codec.Payload, error)
  • func (d *DefaultHandler) HandleGetRelation(ctx context.Context, db database.DB, modelQuery, relatedQuery *query.Scope, ...) (*codec.Payload, error)
  • func (d *DefaultHandler) HandleInsert(ctx context.Context, db database.DB, payload *codec.Payload) (*codec.Payload, error)
  • func (d *DefaultHandler) HandleList(ctx context.Context, db database.DB, q *query.Scope) (*codec.Payload, error)
  • func (d *DefaultHandler) HandleSetRelations(ctx context.Context, db database.DB, model mapping.Model, ...) (*codec.Payload, error)
  • func (d *DefaultHandler) HandleUpdate(ctx context.Context, db database.DB, input *codec.Payload) (*codec.Payload, error)
  • func (d *DefaultHandler) Initialize(c *core.Controller) error
• type ModelHandler
• type Option
  • func WithDefaultHandlerModels(model ...mapping.Model) Option
  • func WithDefaultPageSize(pageSize int) Option
  • func WithMiddlewares(middlewares ...server.Middleware) Option
  • func WithModelHandler(model mapping.Model, handler interface{}) Option
  • func WithNoContentOnInsert() Option
  • func WithPathPrefix(path string) Option
  • func WithPayloadLinks(payloadLinks bool) Option
  • func WithStrictUnmarshal() Option
• type Options

Functions

func MidAccept

func MidAccept(next http.Handler) http.Handler

MidAccept creates a middleware that requires provided accept

func MidContentType

func MidContentType(next http.Handler) http.Handler

MidAccept creates a middleware that requires provided accept

Types

type API

type API struct {
	// AuthenticatorOptions are the settings used for the API mechanics.
	Options *Options
	// Server options set from the neuron core service.
	DB         database.DB
	Controller *core.Controller
	// Endpoints are API endpoints slice created after initialization.
	Endpoints []*server.Endpoint
	// contains filtered or unexported fields
}

API is the neuron handler that implements https://jsonapi.org server routes for neuron models.

func New

func New(options ...Option) *API

New creates new jsonapi API API for the Default Controller.

func (*API) GetEndpoints

func (a *API) GetEndpoints() []*server.Endpoint

GetEndpoints implements server.EndpointsGetter interface.

func (*API) HandleDelete

func (a *API) HandleDelete(model mapping.Model) http.HandlerFunc

HandleDelete handles json:api delete endpoint for the 'model'. Panics if the model is not mapped for given API controller.

func (*API) HandleDeleteRelationship

func (a *API) HandleDeleteRelationship(model mapping.Model, relationName string) http.HandlerFunc

HandleDeleteRelationship handles json:api delete relationship endpoint for the 'model'. Panics if the model is not mapped for given API controller or the relation doesn't exists.

func (*API) HandleGet

func (a *API) HandleGet(model mapping.Model) http.HandlerFunc

HandleGet handles json:api get endpoint for the 'model'. Panics if the model is not mapped for given API controller.

func (*API) HandleGetRelated

func (a *API) HandleGetRelated(model mapping.Model, relationName string) http.HandlerFunc

HandleGetRelation handles json:api get related endpoint for the 'model'. Panics if the model is not mapped for given API controller or relationName is not found.

func (*API) HandleGetRelationship

func (a *API) HandleGetRelationship(model mapping.Model, relationName string) http.HandlerFunc

HandleGetRelationship handles json:api get relationship endpoint for the 'model'. Panics if the model is not mapped for given API controller or the relation doesn't exists.

func (*API) HandleInsert

func (a *API) HandleInsert(model mapping.Model) http.HandlerFunc

HandleInsert handles json:api post endpoint for the 'model'. Panics if the model is not mapped for given API controller.

func (*API) HandleInsertRelationship

func (a *API) HandleInsertRelationship(model mapping.Model, relationName string) http.HandlerFunc

HandleInsertRelationship handles json:api insert relationship endpoint for the 'model'. Panics if the model is not mapped for given API controller or the relation doesn't exists.

func (*API) HandleList

func (a *API) HandleList(model mapping.Model) http.HandlerFunc

HandleList handles json:api list endpoint for the 'model'. Panics if the model is not mapped for given API controller.

func (*API) HandleUpdate

func (a *API) HandleUpdate(model mapping.Model) http.HandlerFunc

HandleUpdate handles json:api list endpoint for the 'model'. Panics if the model is not mapped for given API controller.

func (*API) HandleUpdateRelationship

func (a *API) HandleUpdateRelationship(model mapping.Model, relationName string) http.HandlerFunc

HandleUpdateRelationship handles json:api update relationship endpoint for the 'model'. Panics if the model is not mapped for given API controller or the relation doesn't exists.

func (*API) InitializeAPI

func (a *API) InitializeAPI(c *core.Controller) error

InitializeAPI implements httpServer.API interface.

func (*API) SetRoutes

func (a *API) SetRoutes(router *httprouter.Router) error

Set implements RoutesSetter.

type DefaultHandler

type DefaultHandler struct {
	// contains filtered or unexported fields
}

DefaultHandler is the default json:api handler. It is used as the default handler in the API. The internal fields like 'c' controller would be set by Initialize method.

func (*DefaultHandler) HandleDelete

func (d *DefaultHandler) HandleDelete(ctx context.Context, db database.DB, q *query.Scope) (*codec.Payload, error)

HandleDelete implements api.DeleteHandler interface.

func (*DefaultHandler) HandleGet

func (d *DefaultHandler) HandleGet(ctx context.Context, db database.DB, q *query.Scope) (*codec.Payload, error)

HandleGet implements api.GetHandler interface.

func (*DefaultHandler) HandleGetRelation

func (d *DefaultHandler) HandleGetRelation(ctx context.Context, db database.DB, modelQuery, relatedQuery *query.Scope, relation *mapping.StructField) (*codec.Payload, error)

func (*DefaultHandler) HandleInsert

func (d *DefaultHandler) HandleInsert(ctx context.Context, db database.DB, payload *codec.Payload) (*codec.Payload, error)

HandleInsert implements api.InsertHandler interface.

func (*DefaultHandler) HandleList

func (d *DefaultHandler) HandleList(ctx context.Context, db database.DB, q *query.Scope) (*codec.Payload, error)

HandleList implements api.ListHandler interface.

func (*DefaultHandler) HandleSetRelations

func (d *DefaultHandler) HandleSetRelations(ctx context.Context, db database.DB, model mapping.Model, relationsToSet []mapping.Model, relation *mapping.StructField) (*codec.Payload, error)

HandleSetRelations handles the querySetRelations operations by clearing current model's given relation or setting provided 'relationsToSet'.

func (*DefaultHandler) HandleUpdate

func (d *DefaultHandler) HandleUpdate(ctx context.Context, db database.DB, input *codec.Payload) (*codec.Payload, error)

HandleUpdate implements api.UpdateHandler interface.

func (*DefaultHandler) Initialize

func (d *DefaultHandler) Initialize(c *core.Controller) error

Initialize implements controller initializer.

type ModelHandler

type ModelHandler struct {
	Model   mapping.Model
	Handler interface{}
}

ModelHandler is a struct that matches given Model with its API handler.

type Option

type Option func(o *Options)

func WithDefaultHandlerModels

func WithDefaultHandlerModels(model ...mapping.Model) Option

WithDefaultHandlerModels is an option that sets the models for the API that would use default API handler.

func WithDefaultPageSize

func WithDefaultPageSize(pageSize int) Option

WithDefaultPageSize is an option that sets the default page size.

func WithMiddlewares

func WithMiddlewares(middlewares ...server.Middleware) Option

WithMiddlewares is an option that sets global API middlewares.

func WithModelHandler

func WithModelHandler(model mapping.Model, handler interface{}) Option

WithModelHandler is an option that sets the model handler interfaces.

func WithNoContentOnInsert

func WithNoContentOnInsert() Option

WithNoContentOnInsert is an option that tells API to return http.StatusNoContent if an endpoint allows client generated primary key, and given insert is accepted.

func WithPathPrefix

func WithPathPrefix(path string) Option

WithPathPrefix is an option that sets the API base path. The base path is a path p

func WithPayloadLinks

func WithPayloadLinks(payloadLinks bool) Option

WithPayloadLinks

func WithStrictUnmarshal

func WithStrictUnmarshal() Option

WithStrictUnmarshal sets the api option for strict codec unmarshal.

type Options

type Options struct {
	// PathPrefix is the path prefix used for all endpoints within given API.
	PathPrefix string
	// DefaultPageSize defines default PageSize for the list endpoints.
	DefaultPageSize int
	// NoContentOnCreate allows to set the flag for the models with client generated id to return no content.
	NoContentOnInsert bool
	// StrictFieldsMode defines if the during unmarshal process the query should strictly check
	// if all the fields are well known to given model.
	StrictUnmarshal bool
	// IncludeNestedLimit is a maximum value for nested includes (i.e. IncludeNestedLimit = 1
	// allows ?include=posts.comments but does not allow ?include=posts.comments.author)
	IncludeNestedLimit int
	// FilterValueLimit is a maximum length of the filter values
	FilterValueLimit int
	// MarshalLinks is the default behavior for marshaling the resource links into the handler responses.
	PayloadLinks bool
	// Middlewares are global middlewares added to each endpoint in the given API.
	Middlewares server.MiddlewareChain
	// DefaultHandlerModels are the models assigned to the default API handler.
	DefaultHandlerModels []mapping.Model
	// ModelHandlers are the models with their paired API handlers.
	ModelHandlers []ModelHandler
}

Options is a structure that defines json:api settings.