ols

Documentation

Overview

Package ols is the library behind the ols command line: the HTTP client, request shaping, and the typed data models for the EMBL-EBI Ontology Lookup Service (OLS4).

The Client here is the spine every command shares. It sets a real User-Agent, paces requests so a busy session stays polite, and retries the transient failures (429 and 5xx) that any public API throws under load. Build your endpoint calls and JSON decoding on top of it.

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) Get(ctx context.Context, rawURL string) ([]byte, error)
  • func (c *Client) GetOntologies(ctx context.Context, limit int) ([]Ontology, int, error)
  • func (c *Client) GetTerm(ctx context.Context, oboID, ontology string) (*Term, error)
  • func (c *Client) SearchTerms(ctx context.Context, query, ontology string, limit, offset int) ([]Term, int, error)
• type Domain
  • func (Domain) Classify(input string) (uriType, id string, err error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(uriType, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Ontology
• type Term

Constants

const BaseURL = "https://www.ebi.ac.uk/ols4/api"

BaseURL is the root every request is built from.

const DefaultUserAgent = "ols-cli/0.1.0 (+https://github.com/tamnd/ols-cli)"

DefaultUserAgent identifies the client to OLS4.

const Host = "www.ebi.ac.uk"

Host is the OLS4 site this client talks to.

const HostShort = "ols4"

HostShort is a short display name for the service.

Types

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	// Rate is the minimum gap between requests. Zero means no pacing.
	Rate    time.Duration
	Retries int
	// contains filtered or unexported fields
}

Client talks to OLS4 over HTTP.

func NewClient

func NewClient() *Client

NewClient returns a Client with sensible defaults: a 30s timeout, a 300ms minimum gap between requests, and three retries on transient errors.

func (*Client) Get

func (c *Client) Get(ctx context.Context, rawURL string) ([]byte, error)

Get fetches rawURL and returns the response body. It paces and retries according to the client's settings. The body is read fully and closed here.

func (*Client) GetOntologies

func (c *Client) GetOntologies(ctx context.Context, limit int) ([]Ontology, int, error)

GetOntologies lists ontologies from OLS4. It returns up to limit results.

func (*Client) GetTerm

func (c *Client) GetTerm(ctx context.Context, oboID, ontology string) (*Term, error)

GetTerm fetches a single ontology term by its OBO ID (e.g. "GO:0051301"). It uses the search endpoint to resolve the ID to a canonical term record. The ontology parameter is used to narrow the search when provided.

func (*Client) SearchTerms

func (c *Client) SearchTerms(ctx context.Context, query, ontology string, limit, offset int) ([]Term, int, error)

SearchTerms queries the OLS4 search API and returns matching Term records along with the total count. If ontology is non-empty, results are filtered to that ontology only.

type Domain

type Domain struct{}

Domain is the OLS4 driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (uriType, id string, err error)

Classify turns any accepted input — a bare OBO ID, ontology short name, or full OLS4 URL — into the canonical (type, id).

Rule: if input contains ":" it is a term; otherwise it is an ontology.

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, the hostnames a pasted link is matched against, and the identity reused for the binary's help and version.

func (Domain) Locate

func (Domain) Locate(uriType, id string) (string, error)

Locate is the inverse: the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Ontology

type Ontology struct {
	ID          string `json:"id"          kit:"id"` // ontologyId
	Title       string `json:"title"`
	Description string `json:"description"`
	Prefix      string `json:"prefix"`
	Version     string `json:"version"`
}

Ontology is a single OLS4 ontology record.

type Term

type Term struct {
	ID          string   `json:"id"          kit:"id"` // obo_id
	Label       string   `json:"label"`
	Description string   `json:"description"`
	Ontology    string   `json:"ontology"`
	Prefix      string   `json:"prefix"`
	Synonyms    []string `json:"synonyms"`
	IsObsolete  bool     `json:"is_obsolete"`
}

Term is a single OLS4 ontology term record.