ror

Documentation

Overview

Package ror is the library behind the ror command line: the HTTP client, request shaping, and the typed data models for the Research Organization Registry (ROR) at api.ror.org.

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.

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) FilterOrgs(ctx context.Context, filter string, page int) ([]Org, int, error)
  • func (c *Client) Get(ctx context.Context, rawURL string) ([]byte, error)
  • func (c *Client) GetOrg(ctx context.Context, id string) (*Org, error)
  • func (c *Client) SearchOrgs(ctx context.Context, query string, page int) ([]Org, int, error)
• type Config
  • func DefaultConfig() Config
• 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 Org

Constants

const BaseURL = "https://" + Host

BaseURL is the root every request is built from.

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

DefaultUserAgent identifies the client to ROR.

const Host = "api.ror.org"

Host is the API hostname.

Types

type Client

type Client struct {
	HTTP      *http.Client
	UserAgent string
	BaseURL   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 the ROR API over HTTP.

func NewClient

func NewClient() *Client

NewClient returns a Client built from DefaultConfig.

func (*Client) FilterOrgs

func (c *Client) FilterOrgs(ctx context.Context, filter string, page int) ([]Org, int, error)

FilterOrgs returns organizations matching a ROR filter expression such as "types:Education" or "country.country_code:US". page is 1-based.

func (*Client) Get

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

Get fetches a URL and returns the response body. It paces and retries according to the client's settings.

func (*Client) GetOrg

func (c *Client) GetOrg(ctx context.Context, id string) (*Org, error)

GetOrg fetches a single organization by its ROR ID. id may be a full URL ("https://ror.org/00f54p054") or just the short ID ("00f54p054").

func (*Client) SearchOrgs

func (c *Client) SearchOrgs(ctx context.Context, query string, page int) ([]Org, int, error)

SearchOrgs searches ROR for organizations matching query. page is 1-based. Returns the matching orgs, total result count, and any error.

type Config

type Config struct {
	BaseURL string
	Rate    time.Duration
	Timeout time.Duration
	Retries int
}

Config holds the tunable knobs for a Client.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type Domain

type Domain struct{}

Domain is the ROR 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 into the canonical (type, id).

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 Org

type Org struct {
	ID          string   `json:"id"          kit:"id"`
	Name        string   `json:"name"`
	ShortName   string   `json:"short_name,omitempty"`
	Country     string   `json:"country,omitempty"`
	City        string   `json:"city,omitempty"`
	Status      string   `json:"status,omitempty"`
	Types       []string `json:"types,omitempty"`
	Established int      `json:"established,omitempty"`
	Website     string   `json:"website,omitempty"`
	WikidataID  string   `json:"wikidata_id,omitempty"`
	GridID      string   `json:"grid_id,omitempty"`
}

Org is a Research Organization Registry record.