sdk

README

dp-search-api SDK

Overview

The search API contains a Go client for interacting with the API. The client contains a methods for each API endpoint so that any Go application wanting to interact with the search api can do so. Please refer to the swagger specification as the source of truth of how each endpoint works.

Example use of the API SDK

Initialise new Search API client

package main

import (
	"context"
	"github.com/ONSdigital/dp-search-api/sdk"
)

func main() {
    ...
	searchAPIClient := sdk.NewClient("http://localhost:23900")
    ...
}

Create Index

Use the CreateIndex method to send a request to generate a new search index. This is a private endpoint and requires authorisation header.

...
    // Set authorisation header
    headers := make(map[header][]string)
	headers[Authorisation] = []string{"Bearer authorised-user"}

    resp, err := searchAPIClient.CreateIndex(ctx, sdk.Options{sdk.Headers: headers})
    if err != nil {
        // handle error
    }

    /* If successdul the resp value will be *CreateIndexResponse struct found in github.com/ONSdigital/dp-search-api/models package

    JSON equivalent:
    {
        "index_name": <value>,
    }
    */
...

Get Search Results

Use the GetSearch method to send a request to find search results based on query parameters. Authorisation header needed if hitting private instance of application.

...
    // Set query parameters - no limit to which keys and values you set - please refer to swagger spec for list of available parameters
    query := url.Values{}
    query.Add("q", "census")

    resp, err := searchAPIClient.GetSearch(ctx, sdk.Options{sdk.Query: query})
    if err != nil {
        // handle error
    }
...

Get Release Calendar Entires

Use the GetReleaseCalendarEntries method to send a request to find release calendar entries based on query parameters. Authorisation header needed if hitting private instance of application.

...
    // Set query parameters - no limit to which keys and values you set - please refer to swagger spec for list of available parameters
    query := url.Values{}
    query.Add("q", "census")

    resp, err := searchAPIClient.GetReleaseCalendarEntries(ctx, sdk.Options{sdk.Query: query})
    if err != nil {
        // handle error
    }
...

Handling errors

The error returned from the method contains status code that can be accessed via Status() method and similar to extracting the error message using Error() method; see snippet below:

...
    _, err := searchAPIClient.GetSearch(ctx, Options{})
    if err != nil {
        // Retrieve status code from error
        statusCode := err.Status()
        // Retrieve error message from error
        errorMessage := err.Error()

        // log message, below uses "github.com/ONSdigital/log.go/v2/log" package
        log.Error(ctx, "failed to retrieve search results", err, log.Data{"code": statusCode})

        return err
    }
...

Documentation

Index

• Constants
• Variables
• type Client
  • func New(searchAPIURL string) *Client
  • func NewWithHealthClient(hcCli *healthcheck.Client) *Client
  • func (cli *Client) Checker(ctx context.Context, check *health.CheckState) error
  • func (cli *Client) CreateIndex(ctx context.Context, options Options) (*models.CreateIndexResponse, apiError.Error)
  • func (cli *Client) GetReleaseCalendarEntries(ctx context.Context, options Options) (*transformer.SearchReleaseResponse, apiError.Error)
  • func (cli *Client) GetSearch(ctx context.Context, options Options) (*models.SearchResponse, apiError.Error)
  • func (cli *Client) Health() *healthcheck.Client
  • func (cli *Client) PostSearchURIs(ctx context.Context, options Options, urisRequest api.URIsRequest) (*models.SearchResponse, apiError.Error)
  • func (cli *Client) URL() string
• type Clienter
• type Options
  • func (o *Options) CDIDs(val string) *Options
  • func (o *Options) Census(val string) *Options
  • func (o *Options) ContentType(val string) *Options
  • func (o *Options) DatasetIDs(val string) *Options
  • func (o *Options) Dimensions(val string) *Options
  • func (o *Options) Highlight(val string) *Options
  • func (o *Options) Limit(val string) *Options
  • func (o *Options) NLPWeighting(val string) *Options
  • func (o *Options) Offset(val string) *Options
  • func (o *Options) PopulationTypes(val string) *Options
  • func (o *Options) Q(val string) *Options
  • func (o *Options) Sort(val string) *Options
  • func (o *Options) SubtypeConfirmed(val string) *Options
  • func (o *Options) SubtypePostponed(val string) *Options
  • func (o *Options) SubtypeProvisional(val string) *Options
  • func (o *Options) Topics(val string) *Options
  • func (o *Options) URIPrefix(val string) *Options
• type ResponseInfo

Constants

const (
	// List of available headers
	Authorization string = request.AuthHeaderKey
	CollectionID  string = request.CollectionIDHeaderKey
	FlorenceToken string = request.FlorenceHeaderKey
)

Variables

var (

	// ErrGetPermissionsResponseBodyNil error used when a nil response is returned from the permissions API.
	ErrGetPermissionsResponseBodyNil = errors.New("error creating get permissions request http.Request required but was nil")
)

Types

type Client

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

func New

func New(searchAPIURL string) *Client

New creates a new instance of Client with a given search api url

func NewWithHealthClient

func NewWithHealthClient(hcCli *healthcheck.Client) *Client

NewWithHealthClient creates a new instance of search API Client, reusing the URL and Clienter from the provided healthcheck client

func (*Client) Checker

func (cli *Client) Checker(ctx context.Context, check *health.CheckState) error

Checker calls search api health endpoint and returns a check object to the caller

func (*Client) CreateIndex

func (cli *Client) CreateIndex(ctx context.Context, options Options) (*models.CreateIndexResponse, apiError.Error)

PostSearch creates a new search index

func (*Client) GetReleaseCalendarEntries

func (cli *Client) GetReleaseCalendarEntries(ctx context.Context, options Options) (*transformer.SearchReleaseResponse, apiError.Error)

GetReleaseCalendarEntries gets a list of release calendar entries based on the search request

func (*Client) GetSearch

func (cli *Client) GetSearch(ctx context.Context, options Options) (*models.SearchResponse, apiError.Error)

GetSearch gets a list of search results based on the search request

func (*Client) Health

func (cli *Client) Health() *healthcheck.Client

Health returns the underlying Healthcheck Client for this search API client

func (*Client) PostSearchURIs

func (cli *Client) PostSearchURIs(ctx context.Context, options Options, urisRequest api.URIsRequest) (*models.SearchResponse, apiError.Error)

PostSearchURIs sends a POST request to the /search/uris endpoint

func (*Client) URL

func (cli *Client) URL() string

URL returns the URL used by this client

type Clienter

type Clienter interface {
	Checker(ctx context.Context, check *health.CheckState) error
	CreateIndex(ctx context.Context, options Options) (*models.CreateIndexResponse, apiError.Error)
	GetReleaseCalendarEntries(ctx context.Context, options Options) (*transformer.SearchReleaseResponse, apiError.Error)
	GetSearch(ctx context.Context, options Options) (*models.SearchResponse, apiError.Error)
	PostSearchURIs(ctx context.Context, options Options, urisRequest api.URIsRequest) (*models.SearchResponse, apiError.Error)
	Health() *healthcheck.Client
	URL() string
}

type Options

type Options struct {
	Headers http.Header
	Query   url.Values
}

Options is a struct containing for customised options for the API client

func (*Options) CDIDs

func (o *Options) CDIDs(val string) *Options

CDIDs sets the 'cdids' a.k.a timeseries_id Query parameter to the request

func (*Options) Census

func (o *Options) Census(val string) *Options

Census sets the 'census' Query parameter to the request

func (*Options) ContentType

func (o *Options) ContentType(val string) *Options

ContentType sets the 'content_type' Query parameter to the request

func (*Options) DatasetIDs

func (o *Options) DatasetIDs(val string) *Options

DatasetIDs sets the 'dataset_ids' Query parameter to the request

func (*Options) Dimensions

func (o *Options) Dimensions(val string) *Options

Dimensions sets the 'dimensions' Query parameter to the request

func (*Options) Highlight

func (o *Options) Highlight(val string) *Options

Highlight sets the 'highlight' Query parameter to the request

func (*Options) Limit

func (o *Options) Limit(val string) *Options

Limit sets the 'limit' Query parameter to the request

func (*Options) NLPWeighting

func (o *Options) NLPWeighting(val string) *Options

NLPWeighting sets the 'census' Query parameter to the request

func (*Options) Offset

func (o *Options) Offset(val string) *Options

Offset sets the 'offset' Query parameter to the request

func (*Options) PopulationTypes

func (o *Options) PopulationTypes(val string) *Options

PopulationTypes sets the 'population_types' Query parameter to the request

func (*Options) Q

func (o *Options) Q(val string) *Options

Q sets the 'q' Query parameter to the request

func (*Options) Sort

func (o *Options) Sort(val string) *Options

Sort sets the 'sort' Query parameter to the request

func (*Options) SubtypeConfirmed

func (o *Options) SubtypeConfirmed(val string) *Options

SubtypeConfirmed sets the 'subtype-confirmed' Query parameter to the request

func (*Options) SubtypePostponed

func (o *Options) SubtypePostponed(val string) *Options

SubtypePostponed sets the 'subtype-postponed' Query parameter to the request

func (*Options) SubtypeProvisional

func (o *Options) SubtypeProvisional(val string) *Options

SubtypeProvisional sets the 'subtype-provisional' Query parameter to the request

func (*Options) Topics

func (o *Options) Topics(val string) *Options

Topics sets the 'topics' Query parameter to the request

func (*Options) URIPrefix

func (o *Options) URIPrefix(val string) *Options

URIPrefix sets the 'uri_prefix' Query parameter to the request

type ResponseInfo

type ResponseInfo struct {
	Body    []byte
	Headers http.Header
	Status  int
}