api

README

api

Automatically implements your REST API.

Usage

Create an API instance

myAPI := api.New("/api/", DB)

Parameters:

• The root of all your API routes
• A database handle that fulfills the Database interface

Install on an Aero app

myAPI.Install(app)

This will register all API routes in the app.

Routes

For the following examples we'll assume you have the type Movie registered in the database and that your API root is /api/. Type names are automatically lowercased for all routes.

GET /api/movie/:id

Action: get

Fetches the object with the given ID from the database and shows the JSON representation.

Example response:

If you need to filter out sensitive or private data you can implement the Filter interface on the data type.

POST /api/movie/:id

Action: edit

Writes new data to the object with the given ID. The data needs to be a JSON-formatted map[string]interface where each key stands for a path to a field of this object. The data type needs to implement the Editable interface. Editable fields must be whitelisted with the tag editable using the value true.

Example request:

Alternate example using advanced key paths:

POST /api/new/movie

Action: create

Create a new object of that data type. The data type needs to implement the Creatable interface to register that route. Usually the post body contains a JSON-formatted key/value map which is used as the initial data for the new object.

Example request:

It is up to the developer how the data is interpreted. This API library doesn't make any assumptions about the POST body in create requests.

Style

Please take a look at the style guidelines if you'd like to make a pull request.

Sponsors

Cedric Fung	Scott Rayapoullé	Eduard Urbach

Want to see your own name here?

Documentation

Index

• func SetObjectProperties(obj interface{}, edits map[string]interface{}, ctx aero.Context) error
• type API
  • func New(root string, db Database) *API
  • func (api *API) ActionHandler(action *Action) (string, aero.Handler)
  • func (api *API) ArrayAppend(collection string) (string, aero.Handler)
  • func (api *API) ArrayRemove(collection string) (string, aero.Handler)
  • func (api *API) Create(collection string) (string, aero.Handler)
  • func (api *API) Delete(collection string) (string, aero.Handler)
  • func (api *API) Edit(collection string) (string, aero.Handler)
  • func (api *API) EditField(collection string) (string, aero.Handler)
  • func (api *API) Get(collection string) (string, aero.Handler)
  • func (api *API) GetField(collection string) (string, aero.Handler)
  • func (api *API) Install(app *aero.Application)
  • func (api *API) RegisterAction(action *Action)
  • func (api *API) RegisterActions(collection string, actions []*Action)
  • func (api *API) RegisterCollection(app *aero.Application, collection string, objType reflect.Type)
  • func (api *API) Type(collection string) reflect.Type
• type Action
• type Actionable
• type AfterEditable
• type ArrayEventListener
• type Authorizable
• type Creatable
• type CustomEditable
• type Database
• type Deletable
• type Editable
• type Filter
• type Newable
• type Savable
• type VirtualEditable

Functions

func SetObjectProperties

func SetObjectProperties(obj interface{}, edits map[string]interface{}, ctx aero.Context) error

SetObjectProperties ...

Types

type API

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

API represents your application's API configuration.

func New

func New(root string, db Database) *API

New creates a new API.

func (*API) ActionHandler

func (api *API) ActionHandler(action *Action) (string, aero.Handler)

ActionHandler ...

func (*API) ArrayAppend

func (api *API) ArrayAppend(collection string) (string, aero.Handler)

ArrayAppend ...

func (*API) ArrayRemove

func (api *API) ArrayRemove(collection string) (string, aero.Handler)

ArrayRemove ...

func (*API) Create

func (api *API) Create(collection string) (string, aero.Handler)

Create ...

func (*API) Delete

func (api *API) Delete(collection string) (string, aero.Handler)

Delete ...

func (*API) Edit

func (api *API) Edit(collection string) (string, aero.Handler)

Edit ...

func (*API) EditField

func (api *API) EditField(collection string) (string, aero.Handler)

EditField ...

func (*API) Get

func (api *API) Get(collection string) (string, aero.Handler)

Get returns the route and the handler for the given collection.

func (*API) GetField

func (api *API) GetField(collection string) (string, aero.Handler)

GetField ...

func (*API) Install

func (api *API) Install(app *aero.Application)

Install installs the REST & GraphQL API to your webserver at the given endpoint.

func (*API) RegisterAction

func (api *API) RegisterAction(action *Action)

RegisterAction registers an action for a collection.

func (*API) RegisterActions

func (api *API) RegisterActions(collection string, actions []*Action)

RegisterActions registers actions for a collection.

func (*API) RegisterCollection

func (api *API) RegisterCollection(app *aero.Application, collection string, objType reflect.Type)

RegisterCollection registers a single collection.

func (*API) Type

func (api *API) Type(collection string) reflect.Type

Type ...

type Action

type Action struct {
	Collection string
	Name       string
	Route      string
	Run        func(obj interface{}, ctx aero.Context) error
}

Action defines a single action on a given datatype.

type Actionable

type Actionable interface {
	Authorizable
}

Actionable means the data type can execute actions.

type AfterEditable

type AfterEditable interface {
	AfterEdit(ctx aero.Context) error
}

An AfterEditable is called after the editing process happens and before the object is saved.

type ArrayEventListener

type ArrayEventListener interface {
	OnAppend(ctx aero.Context, field string, index int, obj interface{})
	OnRemove(ctx aero.Context, field string, index int, obj interface{})
}

ArrayEventListener means the data type can authorize changes.

type Authorizable

type Authorizable interface {
	// Authorize returns an error if the given API request is not authorized.
	Authorize(ctx aero.Context, action string) error
}

Authorizable means the data type can authorize changes.

type Creatable

type Creatable interface {
	Create(aero.Context) error
}

Creatable defines an object that can be created with some initial data.

type CustomEditable

type CustomEditable interface {
	Edit(ctx aero.Context, key string, value reflect.Value, newValue reflect.Value) (consumed bool, err error)
}

A CustomEditable has its own implementation on how to edit certain object fields.

type Database

type Database interface {
	Get(collection string, id string) (interface{}, error)
	Set(collection string, id string, obj interface{})
	Delete(collection string, id string) bool
	Types() map[string]reflect.Type
}

Database is an interface for any kind of database.

type Deletable

type Deletable interface {
	Authorizable
	DeleteInContext(aero.Context) error
	Delete() error
}

Deletable defines an object type that can be deleted from the database.

type Editable

type Editable interface {
	Authorizable
	Savable
}

An Editable can authorize changes, be changed and be saved in the database.

type Filter

type Filter interface {
	ShouldFilter(aero.Context) bool
	Filter()
}

Filter describes an object with private data that needs to be filtered in the public API.

type Newable

type Newable interface {
	Savable
	Authorizable
	Creatable
}

Newable defines an object type where new instances can be created by users and saved in the database.

type Savable

type Savable interface {
	// Save saves the object in the database.
	Save()
}

Savable objects can be saved in the database.

type VirtualEditable

type VirtualEditable interface {
	VirtualEdit(ctx aero.Context, key string, newValue reflect.Value) (bool, error)
}

A VirtualEditable has virtual properties that do not really exist but can be set.