jsonapi

README

jsonapi

This is a package for creating JSON:API APIs. It is currently still experimental and not subject to any compatibility guarantees.

Documentation

Overview

This is a package for creating [JSON:API](https://jsonapi.org) APIs. It is currently still experimental and not subject to any compatibility guarantees.

Index

• type API
  • func (api API) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type AnyResourceType
• type AttributeDefinition
• type AttributeResolver
• type RelationshipDefinition
• type RelationshipResolver
• type ResourceType
• type Schema
  • func NewSchema(def *SchemaDefinition) (*Schema, error)
• type SchemaDefinition
• type ToManyRelationshipResolver
  • func (r ToManyRelationshipResolver[T]) AddRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)
  • func (r ToManyRelationshipResolver[T]) RemoveRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)
  • func (r ToManyRelationshipResolver[T]) ResolveRelationship(ctx context.Context, resource T, dataRequested bool, params url.Values) (types.Relationship, *types.Error)
• type ToOneRelationshipResolver
  • func (r ToOneRelationshipResolver[T]) AddRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)
  • func (r ToOneRelationshipResolver[T]) RemoveRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)
  • func (r ToOneRelationshipResolver[T]) ResolveRelationship(ctx context.Context, resource T, dataRequested bool, params url.Values) (types.Relationship, *types.Error)

Types

type API

type API struct {
	Schema *Schema
}

func (API) ServeHTTP

func (api API) ServeHTTP(w http.ResponseWriter, r *http.Request)

type AnyResourceType

type AnyResourceType interface {
	// contains filtered or unexported methods
}

An interface which all ResourceType instantiations implement.

type AttributeDefinition

type AttributeDefinition[T any] struct {
	// Defines the type and implementation of the attribute.
	Resolver AttributeResolver[T]
}

type AttributeResolver

type AttributeResolver[T any] interface {
	// Resolve implementations should compute a value and return a JSON-serializable object.
	ResolveAttribute(ctx context.Context, resource T) (any, *types.Error)
}

type RelationshipDefinition

type RelationshipDefinition[T any] struct {
	// Defines the type and implementation of the relationship.
	Resolver RelationshipResolver[T]
}

type RelationshipResolver

type RelationshipResolver[T any] interface {
	// Implementations should compute a value and return a `types.Relationship` or an error. The
	// relationship will automatically have links added to it, but resolvers may add additional
	// links to the result.
	//
	// If `dataRequested` is false, resolvers may choose to omit the `Data` field from the result.
	//
	// Generally you should use `ToOneRelationshipResolver` or `ToManyRelationshipResolver` instead
	// of implementing this directly.
	ResolveRelationship(ctx context.Context, resource T, dataRequested bool, params url.Values) (types.Relationship, *types.Error)

	// Implementations should add the given members and return a `types.Relationship` or an error.
	// The relationship will automatically have links added to it, but resolvers may add additional
	// links to the result.
	AddRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)

	// Implementations should remove the given members and return a `types.Relationship` or an error.
	// The relationship will automatically have links added to it, but resolvers may add additional
	// links to the result.
	RemoveRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)
}

type ResourceType

type ResourceType[T any] struct {
	// The attributes of the resource type. These must not overlap with the resource relationships.
	Attributes map[string]*AttributeDefinition[T]

	// The relationships of the resource type. These must not overlap with the resource attributes.
	Relationships map[string]*RelationshipDefinition[T]

	// If given, the resource can be directly referenced using an id, e.g. via the /{type_name}/{id}
	// endpoint.
	Get func(ctx context.Context, id string) (T, *types.Error)

	// If given, the resource can be updated, e.g. via the PATCH method on the /{type_name}/{id}
	// endpoint.
	//
	// Relationship values are either `nil`, `types.ResourceId`, or `[]types.ResourceId`.
	Patch func(ctx context.Context, id string, attributes map[string]json.RawMessage, relationships map[string]any) (T, *types.Error)

	// If given, the resource can be created, e.g. via the POST method on the /{type_name} endpoint.
	//
	// Relationship values are either `nil`, `types.ResourceId`, or `[]types.ResourceId`.
	Create func(ctx context.Context, attributes map[string]json.RawMessage, relationships map[string]any) (T, types.ResourceId, *types.Error)

	// If given, the resource can be deleted via the DELETE method on the /{type_name}/{id}
	// endpoint.
	Delete func(ctx context.Context, id string) *types.Error
}

type Schema

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

func NewSchema

func NewSchema(def *SchemaDefinition) (*Schema, error)

type SchemaDefinition

type SchemaDefinition struct {
	// The schema's resource types. Convention is for names to be lowercase, plural name such as
	// "articles".
	ResourceTypes map[string]AnyResourceType
}

type ToManyRelationshipResolver

type ToManyRelationshipResolver[T any] struct {
	ResolveByDefault bool

	Resolve func(ctx context.Context, resource T) ([]types.ResourceId, *types.Error)

	AddMembers func(ctx context.Context, resource T, members []types.ResourceId) ([]types.ResourceId, *types.Error)

	RemoveMembers func(ctx context.Context, resource T, members []types.ResourceId) ([]types.ResourceId, *types.Error)
}

func (ToManyRelationshipResolver[T]) AddRelationshipMembers

func (r ToManyRelationshipResolver[T]) AddRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)

func (ToManyRelationshipResolver[T]) RemoveRelationshipMembers

func (r ToManyRelationshipResolver[T]) RemoveRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)

func (ToManyRelationshipResolver[T]) ResolveRelationship

func (r ToManyRelationshipResolver[T]) ResolveRelationship(ctx context.Context, resource T, dataRequested bool, params url.Values) (types.Relationship, *types.Error)

type ToOneRelationshipResolver

type ToOneRelationshipResolver[T any] struct {
	ResolveByDefault bool

	Resolve func(ctx context.Context, resource T) (*types.ResourceId, *types.Error)
}

func (ToOneRelationshipResolver[T]) AddRelationshipMembers

func (r ToOneRelationshipResolver[T]) AddRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)

func (ToOneRelationshipResolver[T]) RemoveRelationshipMembers

func (r ToOneRelationshipResolver[T]) RemoveRelationshipMembers(ctx context.Context, resource T, members []types.ResourceId) (types.Relationship, *types.Error)

func (ToOneRelationshipResolver[T]) ResolveRelationship

func (r ToOneRelationshipResolver[T]) ResolveRelationship(ctx context.Context, resource T, dataRequested bool, params url.Values) (types.Relationship, *types.Error)