directusapi

README

Directus API client

This is generics golang client for Directus v8 CMS. Never write the same API client again. Just define your collection model and use strongly typed methods.

---

Example usage

// define Read and Write model
type FruitR struct {
    ID          int             `json:"id"`
    Name        string          `json:"name"`
    Weight      float64         `json:"weight"`
}

type FruitW struct {
    Name        string          `json:"name"`
    Weight      float64         `json:"weight"`
}

// initialize generic API client
api := API[FruitR, FruitW, int]{
    Scheme:         "http",
    Host:           "localhost:8080",
    Namespace:      "_",
    CollectionName: "fruits",
    HTTPClient:     http.DefaultClient,
    BearerToken:    "1a2bd3db-8026-4494-ad36-9873ee46c0af"
}

// use typed methods
// - insert
watermelon, err := api.Insert(ctx, FruitW{
	Name:         "watermelon",
	Weight:       20.3,
})
// watermelon's type is FruitR

// - retrieve collection of items
fruits, err := api.Items(ctx, None())
// fruits's type is []FruitR

// update (set) item
passionfruit, err := api.Set(ctx, watermelonID, FruitW{
	Name:         "passionfruit",
	Weight:       3.3,
})
// passionfruit's type is FruitR

Go to the documentation to see all available methods.

Features

• strongly-typed API methods based on directus reference
• different models for reads and writes
• collection querying support: filtering, sorting, limit, offset, fulltext search
• custom directusapi.Time to support Directus API time format
• custom directusapi.Optional to support optional fields

What is Directus?

Directus is open sourced Content Management System, it has UI and exposed API for dynamicly created collections.

Setup

go get github.com/zdebra/directusapi

Limitations

• directus v9 is not supported at this moment; this library was developed for directus v8
• pointers are not allowed in your Read and Write models, directusapi.Optional should be used for optional fields
• directusapi.Time has to be used instead of time.Time

Next steps

• update/create partials to be removed as it could be replaced with directusapi.Optional
• add godoc examples

License

You can check out the full license here

This project is licensed under the terms of the MIT license.

Buy me a coffee

Whether you use this project, have learned something from it, or just like it, please consider supporting it by buying me a coffee, so I can dedicate more time on open-source projects like this :)

Documentation

Index

• func Between(k, v1, v2 string) query
• func Eq(k, v string) query
• func In(k, v string) query
• func Limit(limit int) query
• func Neq(k, v string) query
• func Nnull(k string) query
• func None() query
• func Null(k string) query
• func Offset(offset int) query
• func Search(str string) query
• func SortAsc(sortBy string) query
• func SortDesc(sortBy string) query
• type API
  • func (d API[R, W, PK]) Create(ctx context.Context, partials map[string]any) (R, error)
  • func (d API[R, W, PK]) CreateToken(ctx context.Context, email, password string) (string, error)
  • func (d API[R, W, PK]) Delete(ctx context.Context, id PK) error
  • func (d API[R, W, PK]) GetByID(ctx context.Context, id PK) (R, error)
  • func (d API[R, W, PK]) Insert(ctx context.Context, item W) (R, error)
  • func (d API[R, W, PK]) Items(ctx context.Context, q query) ([]R, error)
  • func (d API[R, W, PK]) Set(ctx context.Context, id PK, item W) (R, error)
  • func (d API[R, W, PK]) Update(ctx context.Context, id PK, partials map[string]any) (R, error)
• type Optional
  • func SetOptional[T any](val T) Optional[T]
  • func UnsetOptional[T any]() Optional[T]
  • func (o Optional[T]) IsSet() bool
  • func (o Optional[T]) MarshalJSON() ([]byte, error)
  • func (o *Optional[T]) UnmarshalJSON(data []byte) error
  • func (o Optional[T]) ValueMust() T
  • func (o Optional[T]) ValueOrZero() T
• type PrimaryKey
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t *Time) UnmarshalJSON(data []byte) error
• type Version

Functions

func Between

func Between(k, v1, v2 string) query

func Eq

func Eq(k, v string) query

func In

func In(k, v string) query

func Limit

func Limit(limit int) query

func Neq

func Neq(k, v string) query

func Nnull

func Nnull(k string) query

func None

func None() query

func Null

func Null(k string) query

func Offset

func Offset(offset int) query

func Search

func Search(str string) query

func SortAsc

func SortAsc(sortBy string) query

func SortDesc

func SortDesc(sortBy string) query

Types

type API

type API[R, W any, PK PrimaryKey] struct {
	Scheme         string
	Host           string
	Namespace      string
	CollectionName string
	BearerToken    string
	HTTPClient     *http.Client

	Version Version
	// contains filtered or unexported fields
}

API is a generic API client for any Directus collection R is a read model W is a write model PK is a type of primary key

func (API[R, W, PK]) Create

func (d API[R, W, PK]) Create(ctx context.Context, partials map[string]any) (R, error)

Create attempts to create new item with partials

Related Directus reference: https://v8.docs.directus.io/api/items.html#create-an-item

func (API[R, W, PK]) CreateToken

func (d API[R, W, PK]) CreateToken(ctx context.Context, email, password string) (string, error)

CreateToken uses provided credentials to generate server token

Related Directus reference: https://v8.docs.directus.io/api/authentication.html#retrieve-a-temporary-access-token

func (API[R, W, PK]) Delete

func (d API[R, W, PK]) Delete(ctx context.Context, id PK) error

Delete removes item with a given id

Related Directus reference: https://v8.docs.directus.io/api/items.html#update-an-item

func (API[R, W, PK]) GetByID

func (d API[R, W, PK]) GetByID(ctx context.Context, id PK) (R, error)

GetByID reads a single item by given ID

Related Directus reference: https://v8.docs.directus.io/api/items.html#retrieve-an-item

func (API[R, W, PK]) Insert

func (d API[R, W, PK]) Insert(ctx context.Context, item W) (R, error)

Insert attempts to insert new item

Related Directus reference: https://v8.docs.directus.io/api/items.html#create-an-item

func (API[R, W, PK]) Items

func (d API[R, W, PK]) Items(ctx context.Context, q query) ([]R, error)

Items retrieves a collection of items

Related Directus reference: https://v8.docs.directus.io/api/items.html#update-an-item

func (API[R, W, PK]) Set

func (d API[R, W, PK]) Set(ctx context.Context, id PK, item W) (R, error)

Set performs an update of an item with given id

Related Directus reference: https://v8.docs.directus.io/api/items.html#update-an-item

func (API[R, W, PK]) Update

func (d API[R, W, PK]) Update(ctx context.Context, id PK, partials map[string]any) (R, error)

Update performs partial update of an item with given id

Related Directus reference: https://v8.docs.directus.io/api/items.html#update-an-item

type Optional

type Optional[T any] struct {
	// contains filtered or unexported fields
}

func SetOptional

func SetOptional[T any](val T) Optional[T]

func UnsetOptional

func UnsetOptional[T any]() Optional[T]

func (Optional[T]) IsSet

func (o Optional[T]) IsSet() bool

func (Optional[T]) MarshalJSON

func (o Optional[T]) MarshalJSON() ([]byte, error)

func (*Optional[T]) UnmarshalJSON

func (o *Optional[T]) UnmarshalJSON(data []byte) error

func (Optional[T]) ValueMust

func (o Optional[T]) ValueMust() T

func (Optional[T]) ValueOrZero

func (o Optional[T]) ValueOrZero() T

type PrimaryKey

type PrimaryKey interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~string
}

type Time

type Time struct {
	time.Time
}

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

type Version

type Version int

const (
	V8 Version = iota
	V9
)