golark

README

golark

Golark makes it easy to build Skylark API requests in golang.

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

type episode struct {
	Title        string   `json:"title"`
	Subtitle     string   `json:"subtitle"`
	UID          string   `json:"uid"`
	DataSourceID string   `json:"data_source_id"`
	Items        []string `json:"items"`
}

func main() {
	var ep episode

	// request an object
	golark.NewRequest("https://test.com/api/", "episodes", "ep_123").
		Execute(&ep)

	// request an object with only certain fields
	golark.NewRequest("https://test.com/api/", "episodes", "ep_123").
		AddField(golark.NewField("title")).
		AddField(golark.NewField("subtitle")).
		AddField(golark.NewField("uid")).
		Execute(&ep)

	type container struct {
		Objects []episode `json:"objects"`
	}

	var eps container

	// request all members of a collection
	golark.NewRequest("https://test.com/api/", "episodes", "").
		Execute(&eps)

	// request all members of a collection with certain properties
	golark.NewRequest("https://test.com/api/", "episodes", "").
		WithFilter("title", golark.NewFilter(golark.Equals, "test episode title")).
		Execute(&eps)
}

Documentation

Index

• Constants
• type Field
  • func NewField(name string) *Field
  • func (f *Field) Expand(subField *Field) *Field
  • func (f *Field) WithFilter(filter *Filter) *Field
  • func (f *Field) WithSubField(subField *Field) *Field
• type Filter
  • func NewFilter(c constraint, value string) *Filter
• type Request
  • func NewRequest(endpoint, collection, id string) *Request
  • func (r *Request) AddField(f *Field) *Request
  • func (r *Request) Execute(v interface{}) error
  • func (r *Request) Expand(f *Field) *Request
  • func (r *Request) Headers(h http.Header) *Request
  • func (r *Request) OrderBy(f *Field, order order) *Request
  • func (r *Request) QueryParams() url.Values
  • func (r *Request) ToURL() (*url.URL, error)
  • func (r *Request) WithClient(client *http.Client) *Request
  • func (r *Request) WithContext(ctx context.Context) *Request
  • func (r *Request) WithFilter(fieldName string, filter *Filter) *Request

Examples

• Field.WithSubField
• Request
• Request (All)
• Request.AddField
• Request.Expand
• Request.OrderBy
• Request.WithFilter
• Request.WithFilter (Greater_than)
• Request.WithFilter (Multiple)

Constants

const (
	// GreaterThan contrains to fields that are greater than a given value
	GreaterThan = constraint("gt")
	// LessThan contrains to fields that are less than a given value
	LessThan = constraint("lt")
	// Equals contrains to fields that equal a given value
	Equals = constraint("")
)

const (
	// Ascending is used to sort by ascending
	Ascending = order("")
	// Descending is used to sort by descending
	Descending = order("-")
)

Types

type Field

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

Field represents a Skylark request field

func NewField

func NewField(name string) *Field

NewField creates a new field

func (*Field) Expand

func (f *Field) Expand(subField *Field) *Field

Expand expands a field without explicitly listing it as a field to return. This is usefult if you want to return all fields.

func (*Field) WithFilter

func (f *Field) WithFilter(filter *Filter) *Field

WithFilter applies a fielter to the field.

func (*Field) WithSubField

func (f *Field) WithSubField(subField *Field) *Field

WithSubField expands a field and adds the given field to the list of filds to be returned. Only use this if the field is a reference to a different object!

Example

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	golark.NewRequest("https://test.com/api/", "person", "").
		AddField(golark.NewField("first_name")).
		AddField(golark.NewField("team_url").
			WithSubField(golark.NewField("name")).
			WithSubField(golark.NewField("nation_url").
				WithSubField(golark.NewField("name"))))
}

type Filter

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

Filter represents a Skylark request filter It is used to constrain a request by a field's value

func NewFilter

func NewFilter(c constraint, value string) *Filter

NewFilter creates a new filter with a given constraint and value

type Request

type Request struct {
	Endpoint   string
	Collection string
	ID         string
	Context    context.Context
	Client     *http.Client
	// contains filtered or unexported fields
}

Request represents a Skylark API request

Example

This is the most basic way to make a request. It will request the person with ID "pers_123" with all it's fields.

package main

import (
	"log"

	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	type person struct {
		FirstName string `json:"first_name"`
		LastName  string `json:"last_name"`
	}

	var p person

	r := golark.NewRequest("https://test.com/api/", "person", "pers_123")
	err := r.Execute(&p)
	if err != nil {
		log.Fatal(err)
	}
}

Example (All)

If you leave the ID empty all members of the collection will be queried. You usually want to avoid this unless you limit the request to certain fields.

package main

import (
	"log"

	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	type person struct {
		FirstName string `json:"first_name"`
		LastName  string `json:"last_name"`
	}

	type response struct {
		Objects []person `json:"objects"`
	}

	var people []response

	r := golark.NewRequest("https://test.com/api/", "person", "")
	err := r.Execute(&people)
	if err != nil {
		log.Fatal(err)
	}
}

func NewRequest

func NewRequest(endpoint, collection, id string) *Request

NewRequest returns a simple request with the given

func (*Request) AddField

func (r *Request) AddField(f *Field) *Request

AddField adds a field to the request. If a request has fields specified it will only return those fields.

Example

AddField lets you limit requests to certain fields, this can speed them up significantly.

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	golark.NewRequest("https://test.com/api/", "person", "pers_123").
		AddField(golark.NewField("first_name")).
		AddField(golark.NewField("last_name"))
}

func (*Request) Execute

func (r *Request) Execute(v interface{}) error

Execute executes the request and writes it's results to the value pointed to by v.

func (*Request) Expand

func (r *Request) Expand(f *Field) *Request

Expand expands a field without explicitly listing it as a field to return. This is usefult if you want to return all fields.

Example

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	golark.NewRequest("https://test.com/api/", "person", "pers_123").
		Expand(golark.NewField("team_url"))
}

func (*Request) Headers

func (r *Request) Headers(h http.Header) *Request

Headers lets you set http headers that will be used for HTTP requests

func (*Request) OrderBy

func (r *Request) OrderBy(f *Field, order order) *Request

OrderBy sorts the response by the given field

Example

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	golark.NewRequest("https://test.com/api/", "person", "").
		OrderBy(golark.NewField("first_name"), golark.Ascending)
}

func (*Request) QueryParams

func (r *Request) QueryParams() url.Values

QueryParams calculates and returns the request's query parameters.

func (*Request) ToURL

func (r *Request) ToURL() (*url.URL, error)

ToURL converts the request into a url.URL

func (*Request) WithClient

func (r *Request) WithClient(client *http.Client) *Request

WithClient lets you set a client that will be used for HTTP requests by default http.DefaultCLient is used

func (*Request) WithContext

func (r *Request) WithContext(ctx context.Context) *Request

WithContext set's the context the request will be executed with. by default context.Background() is used

func (*Request) WithFilter

func (r *Request) WithFilter(fieldName string, filter *Filter) *Request

WithFilter allows to filter by a field that is not in the requested response

Example

Filters are helpful to search for objects with knowing their ID

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	golark.NewRequest("https://test.com/api/", "person", "").
		WithFilter("first_name", golark.NewFilter(golark.Equals, "Bob"))
}

Example (Greater_than)

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	golark.NewRequest("https://test.com/api/", "person", "").
		WithFilter("salary", golark.NewFilter(golark.GreaterThan, "10000"))
}

Example (Multiple)

You can use comma separated lists to query multiple objects at once.

package main

import (
	"github.com/SoMuchForSubtlety/golark"
)

func main() {
	golark.NewRequest("https://test.com/api/", "person", "").
		WithFilter("first_name", golark.NewFilter(golark.Equals, "Bob,Lucas,Sue"))
}