rest

Documentation

Overview

Package rest implements a REST API for korrel8r.

Note: Comments starting with "@" are used to generate a swagger spec via 'go generate'. Static swagger doc is available at ./doc/swagger.md. dynamic HTML doc is available from korrel8r at the "/api" endpoint.

@title			REST API
@description	REST API for the Korrel8r correlation engine.
@version		v1alpha1
@license.name	Apache 2.0
@license.url	https://github.com/korrel8r/korrel8r/blob/main/LICENSE
@contact.name	Project Korrel8r
@contact.url	https://github.com/korrel8r/korrel8r
@basePath		/api/v1alpha1
@schemes		http https
@accept			json
@produce		json

Index

• Variables
• type API
  • func New(e *engine.Engine, c config.Configs, r *gin.Engine) (*API, error)
  • func (a *API) Close()
  • func (a *API) GetConfiguration(c *gin.Context)
  • func (a *API) GetDomainClasses(c *gin.Context)
  • func (a *API) GetDomains(c *gin.Context)
  • func (a *API) GetObjects(c *gin.Context)
  • func (a *API) GraphsGoals(c *gin.Context)
  • func (a *API) GraphsNeighbours(c *gin.Context)
  • func (a *API) ListsGoals(c *gin.Context)
• type Classes
• type Domain
• type Edge
• type GoalsRequest
• type Graph
• type GraphOptions
• type NeighboursRequest
• type Node
• type QueryCount
• type QueryOptions
• type Rule
• type Start
• type StoresStatus

Variables

var BasePath = docs.SwaggerInfo.BasePath

BasePath is the versioned base path for the current version of the REST API.

Types

type API

type API struct {
	Engine  *engine.Engine
	Configs config.Configs
}

func New

func New(e *engine.Engine, c config.Configs, r *gin.Engine) (*API, error)

New API instance, registers handlers with a gin Engine.

func (*API) Close

func (a *API) Close()

Close cleans any persistent resources.

func (*API) GetConfiguration

func (a *API) GetConfiguration(c *gin.Context)

GetConfiguration handler

@router		/configuration [get]
@summary	Dump configuration files and their contents.
@tags		configuration
@success	200	{object}	config.Configs

func (*API) GetDomainClasses

func (a *API) GetDomainClasses(c *gin.Context)

GetDomainClasses handler

@router		/domains/{domain}/classes [get]
@summary	Get class names and descriptions for the domain.
@param		domain	path	string	true	"Domain to get classes from."
@tags		configuration
@success	200	{object}	Classes

func (*API) GetDomains

func (a *API) GetDomains(c *gin.Context)

GetDomains handler

@router		/domains [get]
@summary	List all configured domains and stores.
@tags		configuration
@success	200	{array}	Domain

func (*API) GetObjects

func (a *API) GetObjects(c *gin.Context)

GetObjects handler

@router		/objects [get]
@summary	Execute a query, returns a list of JSON objects.
@param		query	query	string	true	"query string"
@tags		search
@success	200	{array}	any

func (*API) GraphsGoals

func (a *API) GraphsGoals(c *gin.Context)

GraphsGoals handler.

@router		/graphs/goals [post]
@summary	Create a correlation graph from start objects to goal queries.
@param		withRules	query	bool			false	"include rules in graph edges"
@param		start		body	GoalsRequest	true	"search from start to goal classes"
@tags		search
@success	200	{object}	Graph

func (*API) GraphsNeighbours

func (a *API) GraphsNeighbours(c *gin.Context)

GraphsNeighbours handler

@router		/graphs/neighbours [post]
@summary	Create a correlation graph of neighbours of a start object to a given depth.
@param		withRules	query	bool				false	"include rules in graph edges"
@param		start		body	NeighboursRequest	true	"search from neighbours"
@tags		search
@success	200	{object}	Graph

func (*API) ListsGoals

func (a *API) ListsGoals(c *gin.Context)

ListsGoals handler.

@router		/lists/goals [post]
@summary	Generate a list of goal nodes related to a starting point.
@param		start	body	GoalsRequest	true	"search from start to goal classes"
@tags		search
@success	200	{array}	Node

type Classes

type Classes map[string]string

@description Classes maps class names to a short description.

type Domain

type Domain struct {
	Name   string         `json:"name"`
	Stores []config.Store `json:"stores,omitempty"`
	Errors []string       `json:"errors,omitempty"`
}

FIXME here @description Domain configuration information.

type Edge

type Edge struct {
	// Start is the class name of the start node.
	Start string `json:"start"`
	// Goal is the class name of the goal node.
	Goal string `json:"goal" example:"domain:class"`
	// Rules is the set of rules followed along this edge (optional).
	Rules []Rule `json:"rules,omitempty"`
}

Directed edge in the result graph, from Start to Goal classes.

type GoalsRequest

type GoalsRequest struct {
	// Start of correlation search.
	Start Start `json:"start"`
	// Goal classes for correlation.
	Goals []string `json:"goals,omitempty" example:"domain:class"`
}

@description Starting point for a goals search.

type Graph

type Graph struct {
	Nodes []Node `json:"nodes"`
	Edges []Edge `json:"edges,omitempty"`
}

@description Graph resulting from a correlation search.

type GraphOptions

type GraphOptions struct {
	// WithRules if true include rules in the graph edges.
	WithRules bool `form:"withRules"`
}

GraphOptions control the format of the graph

type NeighboursRequest

type NeighboursRequest struct {
	// Start of correlation search.
	Start Start `json:"start"`
	// Max depth of neighbours graph.
	Depth int `json:"depth"`
}

@description Starting point for a neighbours search.

type Node

type Node struct {
	// Class is the full class name in "DOMAIN:CLASS" form.
	Class string `json:"class" example:"domain:class"`
	// Queries yielding results for this class.
	Queries []QueryCount `json:"queries,omitempty"`
	// Count of results found for this class, after de-duplication.
	Count int `json:"count"`
}

Node in the result graph, contains results for a single class.

type QueryCount

type QueryCount struct {
	// Query for correlation data.
	Query string `json:"query"`
	// Count of results or -1 if the query was not executed.
	Count int `json:"count"`
}

@description Query run during a correlation with a count of results found.

type QueryOptions

type QueryOptions struct {
	// Query string to execute.
	Query string `form:"query"`
	// Constraint (optional) to limit the results.
	Constraint *korrel8r.Constraint `json:"constraint,omitempty"`
}

QueryOptions provides a query to execute.

type Rule

type Rule struct {
	// Name is an optional descriptive name.
	Name string `json:"name,omitempty"`
	// Queries generated while following this rule.
	Queries []QueryCount `json:"queries,omitempty"`
}

Rule is a correlation rule with a list of queries and results counts found during navigation. Rules form a directed multi-graph over classes in the result graph.

type Start

type Start struct {
	// Class of starting objects
	Class string `json:"class,omitempty"`
	// Queries for starting objects, must return the start class.
	Queries []string `json:"queries,omitempty"`
	// Objects serialized as JSON to, must be of start class.
	Objects []json.RawMessage `json:"objects,omitempty" swaggertype:"object"`
	// Constraint (optional) to limit the results.
	Constraint *korrel8r.Constraint `json:"constraint,omitempty"`
}

@description Starting point for correlation. The starting object set includes: - results from getting each of the [Start.Queries] - unmarshalled objects from [Start.Objects]

type StoresStatus

type StoresStatus struct {
}

@description StoreStatus contains status of known stores.