Documentation ¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrMissingInput occurs when a function is called without input parameters (e.g. nil slice) ErrMissingInput = errors.New("missing input parameters") // ErrBlankArgument occurs when a function is called with a blank argument that should not be blank. ErrBlankArgument = errors.New("a provided argument is blank or empty") // ErrNegativeInput occurs when a function is called with a negative number that should not be negative. ErrNegativeInput = errors.New("input cannot be a negative number") )
Functions ¶
func NewRequest ¶
NewRequest returns a request configured for the provided url using the provided method. The provided query options are written to the body of the request. The default method is GET.
Types ¶
type Option ¶
Option is a functional option type used to set the filters for an API query. Option is the first-order function returned by the available functional options (e.g. Fields or Limit). For the full list of supported filters and their expected syntax, please visit: https://apicalypse.io/syntax/
func ComposeOptions ¶
ComposeOptions composes multiple functional options into a single Option. This is primarily used to create a single functional option that can be used repeatedly across multiple queries.
Example ¶
// Composing FuncOptions to filter out unpopular results composedOpts := ComposeOptions( Fields("title", "username", "game", "likes", "content"), Where("likes > 10"), Where("views >= 200"), Limit(25), ) // Using composed FuncOptions req1, err := NewRequest("GET", "https://some-internet-game-database-api/games/", composedOpts) if err != nil { fmt.Println(err) return } // Reusing composed FuncOptions req2, err := NewRequest("GET", "https://some-internet-game-database-api/games/", composedOpts, Offset(25)) if err != nil { fmt.Println(err) return } // Retrieves first set of 15 popular games http.DefaultClient.Do(req1) // Retrieves second set of 15 popular games http.DefaultClient.Do(req2)
Output:
func Exclude ¶
Exclude is a functional option for setting the excluded fields in the results from a query.
Example ¶
// Retrieve games without name field req, _ := NewRequest("GET", "https://some-internet-game-database-api/games/", Exclude("name")) // Retrieve games without genres field req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Exclude("genres")) // Retrieve games without name or genres field req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Exclude("name", "genres")) // Retrieve games without parent game req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Exclude("parent_game")) // Retrieve games without parent game name req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Exclude("parent_game.name")) // Retrieve games without any number of fields req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Exclude("name", "genres", "popularity", "rating")) // Execute latest request http.DefaultClient.Do(req)
Output:
func Fields ¶
Fields is a functional option for setting the included fields in the results from a query.
Example ¶
// Retrieve games with name field req, _ := NewRequest("GET", "https://some-internet-game-database-api/games/", Fields("name")) // Retrieve games with genres field req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Fields("genres")) // Retrieve games with both name and genres field req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Fields("name", "genres")) // Retrieve games with a parent game req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Fields("parent_game")) // Retrieve games with a parent game name req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Fields("parent_game.name")) // Retrieve games with any number of fields req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Fields("name", "genres", "popularity", "rating")) // Retrieve games with all available fields req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Fields("*")) // Execute latest request http.DefaultClient.Do(req)
Output:
func Limit ¶
Limit is a functional option for setting the number of items to return from a query. This usually has a maximum limit.
Example ¶
// Retrieve up to 1 result req, _ := NewRequest("GET", "https://some-internet-game-database-api/games/", Limit(1)) // Retrieve up to 25 results req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Limit(25)) // Retrieve up to 50 results req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Limit(50)) // Execute latest request http.DefaultClient.Do(req)
Output:
func Offset ¶
Offset is a functional option for setting the index to start returning results from a query.
Example ¶
// Retrieve the first batch of 10 results req, _ := NewRequest("GET", "https://some-internet-game-database-api/games/", Limit(10)) // Retrieve the second batch of 10 results req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Limit(10), Offset(10)) // Retrieve the third batch of 10 results req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Limit(10), Offset(20)) // Retrieve the fourth batch of 10 results req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Limit(10), Offset(30)) http.DefaultClient.Do(req)
Output:
func Search ¶
Search is a functional option for searching for a value in a particular column of data. If the column is omitted, search will be performed on the default column.
Example ¶
// Search for results with the name "Halo" req, _ := NewRequest("GET", "https://some-internet-game-database-api/search/", Search("", "Halo")) // Search for results with the name "Zelda" req, _ = NewRequest("GET", "https://some-internet-game-database-api/search/", Search("", "Zelda")) http.DefaultClient.Do(req)
Output:
func Sort ¶
Sort is a functional option for sorting the results of a query by a certain field's values and the use of "asc" or "desc" to sort by ascending or descending order.
Example ¶
// Retrieve the most popular games req, _ := NewRequest("GET", "https://some-internet-game-database-api/games/", Sort("popularity", "desc")) // Retrieve the least popular games req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Sort("popularity", "asc")) // Retrieve the earliest released games by their first release date req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Sort("first_release_date", "asc")) // Retrieve games with the latest release date req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Sort("first_release_date", "desc")) http.DefaultClient.Do(req)
Output:
func Where ¶
Where is a functional option for setting a custom data filter similar to SQL. If multiple filters are provided, they are AND'd together. For the full list of filters and more information, visit: https://apicalypse.io/syntax/
Example ¶
// Retrieve games with a rating equal to 50 req, _ := NewRequest("GET", "https://some-internet-game-database-api/games/", Where("rating = 50")) // Retrieve games with a rating not equal to 50 req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("rating != 50")) // Retrieve games with a rating greater than 50 req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("rating > 50")) // Retrieve games with a rating greater than or equal to 50 req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("rating >= 50")) // Retrieve games with a rating less than 50 req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("rating < 50")) // Retrieve games with a rating less than or equal to 50 req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("rating <= 50")) // Retrieve games with all of the following genres: Roleplaying, Adventure, and MMO req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("genres = [Roleplaying, Adventure, MMO]")) // Retrieve games without all of the following genres: genres Roleplaying, Adventure, and MMO req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("genres != [Roleplaying, Adventure, MMO]")) // Retrieve games with at least one of the following genres: Roleplaying, Adventure, or MMO req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("genres = (Roleplaying, Adventure, MMO)")) // Retrieve games without any of the following genres: Roleplaying, Adventure, or MMO req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("genres != (Roleplaying, Adventure, MMO)")) // Retrieve games with exclusively the following genres: Roleplaying, Adventure, or MMO req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("genres = {Roleplaying, Adventure, MMO}")) // Retrieve games with a rating greater than 50 AND with at least one of the following genres: Roleplaying, Adventure, or MMO req, _ = NewRequest("GET", "https://some-internet-game-database-api/games/", Where("rating > 50", "genres = (Roleplaying, Adventure, MMO)")) // Execute latest request http.DefaultClient.Do(req)
Output: