census

Documentation

Index

• Constants
• func BuildURL(id, verb, game, col string, opts ...URLOption) *url.URL
• type Client
  • func (cl Client) Count(col string, opts ...URLOption) (int, error)
  • func (cl Client) Fetch(verb, col string, opts ...URLOption) ([]byte, error)
  • func (cl Client) Get(dst interface{}, col string, opts ...URLOption) error
• type Error
  • func (err Error) Error() string
• type Sort
  • func (s Sort) String() string
• type SortDir
• type URLOption
  • func DistinctOption(field string) URLOption
  • func ExactMatchFirstOption() URLOption
  • func HasOption(fields ...string) URLOption
  • func HideOption(fields ...string) URLOption
  • func IgnoreCaseOption() URLOption
  • func IncludeNullOption() URLOption
  • func LangOption(lang string) URLOption
  • func LimitOption(limit int) URLOption
  • func LimitPerDBOption(limit int) URLOption
  • func NoRetryOption() URLOption
  • func ResolveOption(fields ...string) URLOption
  • func SearchOption(name, val string) URLOption
  • func ShowOption(fields ...string) URLOption
  • func SortOption(sorts ...Sort) URLOption
  • func StartOption(start int) URLOption
  • func TimingOption() URLOption

Constants

const (

	// DefaultServiceID is the ID which is used when none is specified.
	DefaultServiceID = "example"
)

Functions

func BuildURL

func BuildURL(id, verb, game, col string, opts ...URLOption) *url.URL

BuildURL builds a request URL from the various components.

id:   The service ID.
verb: The type of request. Usually `get` or `count`.
game: The namespace. For example, `ps2`.
col:  The collection type. For example, `character`.
opts: A list of options. See the example for more information.

Types

type Client

type Client struct {
	// ServiceID is the ID to use when making API requests. If it is
	// blank, DefaultServiceID is used.
	ServiceID string

	// Game is the namespace to use. Examples are `ps2`, `ps2ps4us`,
	// `eq2`, etc.
	Game string

	// HTTPClient is the client to use for making API requests. If it is
	// nil, http.DefaultClient is used.
	HTTPClient *http.Client
}

A Client is the main interface for the Census API.

func (Client) Count

func (cl Client) Count(col string, opts ...URLOption) (int, error)

Count performs a request to the API using a `count` verb. It returns the returned count and an error. If an error is encountered, the value of the returned int is undefined.

Like with Fetch, if the API yields an error, the returned error will be of type *Error.

func (Client) Fetch

func (cl Client) Fetch(verb, col string, opts ...URLOption) ([]byte, error)

Fetch returns the raw JSON that the API returns for a request. If the API itself has an error, such as

{"error":"No data found."}

then the returned error will be an *Error.

For more information about the arguments, see BuildURL.

func (Client) Get

func (cl Client) Get(dst interface{}, col string, opts ...URLOption) error

Get performs a request to the API using a `get` verb. It decodes the returned JSON into dst.

Like with Fetch, if the API yields an error, the returned error will be of type *Error.

type Error

type Error struct {
	Err string `json:"error"`
}

An Error represents an error that is returned by the API.

func (Error) Error

func (err Error) Error() string

type Sort

type Sort struct {
	Field string
	Dir   SortDir
}

A Sort is a mapping of field names to sort directions.

func (Sort) String

func (s Sort) String() string

type SortDir

type SortDir int

A SortDir is a direction to sort a field.

const (
	// Desc is descending order.
	Desc SortDir = iota - 1

	// DefaultDir is an unspecified order.
	DefaultDir

	// Asc is ascending order.
	Asc
)

type URLOption

type URLOption func(url.Values)

A URLOption is an option that is passed to the API.

func DistinctOption

func DistinctOption(field string) URLOption

DistinctOption specifies that all distinct values of a field should be returned. It cooresponds to `c:distinct`.

func ExactMatchFirstOption

func ExactMatchFirstOption() URLOption

ExactMatchFirstOption specifies that an exact match should always be the first result. It cooresponds to `c:exactMatchFirst=true`.

func HasOption

func HasOption(fields ...string) URLOption

HasOption filters objects by the presence of fields. It cooresponds to `c:has`.

func HideOption

func HideOption(fields ...string) URLOption

HideOption is a list of fields to hide. It cooresponds to `c:hide`.

func IgnoreCaseOption

func IgnoreCaseOption() URLOption

IgnoreCaseOption makes searches case-insensetive. It cooresponds to `c:case=false`.

func IncludeNullOption

func IncludeNullOption() URLOption

IncludeNullOption enables null field values. It cooresponds to `c:includeNull=true`.

func LangOption

func LangOption(lang string) URLOption

LangOption specifies what language to return in multi-lingual results. It cooresponds to `c:lang`.

func LimitOption

func LimitOption(limit int) URLOption

LimitOption limits the number of returned results. It cooresponds to `c:limit`.

func LimitPerDBOption

func LimitPerDBOption(limit int) URLOption

LimitPerDBOption is a different type of limit on the number of returned result than LimitOption. It cooresponds to `c:limitPerDB`.

func NoRetryOption

func NoRetryOption() URLOption

NoRetryOption specifies that the API shouldn't automatically retry on failures. It cooresponds to `c:retry=false`.

func ResolveOption

func ResolveOption(fields ...string) URLOption

ResolveOption is a list of resolves. It cooresponds to `c:resolve`.

func SearchOption

func SearchOption(name, val string) URLOption

SearchOption is a search request. For example,

SearchOption("name.first_lower", "deedlefaketr")

produces

name.first_lower=deedlefaketr

func ShowOption

func ShowOption(fields ...string) URLOption

ShowOption is a list of fields to show. It cooresponds to `c:show`.

func SortOption

func SortOption(sorts ...Sort) URLOption

SortOption is a list of fields to sort by. It cooresponds to `c:sort`.

func StartOption

func StartOption(start int) URLOption

StartOption specifies the index of the first result. It cooresponds to `c:start`.

func TimingOption

func TimingOption() URLOption

TimingOption adds a field in the top-level struct that gives the time the API servers spent fetching data from the database. It cooresponds to `c:timing=true`.