golark

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 13, 2021 License: GPL-3.0 Imports: 7 Imported by: 1

README

GoDoc Go Report Card

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

Examples

Constants

View Source
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("")
)
View Source
const (
	// Ascending is used to sort by ascending
	Ascending = order("")
	// Descending is used to sort by descending
	Descending = order("-")
)

Variables

This section is empty.

Functions

This section is empty.

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"))))
}
Output:

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)
	}
}
Output:

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)
	}
}
Output:

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"))
}
Output:

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"))
}
Output:

func (*Request) Headers added in v1.2.0

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)
}
Output:

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 added in v1.1.0

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"))
}
Output:

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"))
}
Output:

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"))
}
Output:

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL