Documentation ¶
Overview ¶
Package sherpa is a server and client library for Sherpa API's.
NOTE: this is work in progress and will likely change.
Sherpa API's are similar to JSON-RPC, but discoverable and self-documenting. Sherpa is defined at https://www.ueber.net/who/mjl/sherpa/.
Use sherpa.NewHandler to export Go functions using a http.Handler. sherpa.NewClient creates an API client for calling remote functions.
Index ¶
Constants ¶
const ( SherpaClientError = "sherpaClientError" // error from client library when calling an API function SherpaBadResponse = "sherpaBadResponse" // bad response from server, e.g. JSON response body could not be parsed SherpaHttpError = "sherpaHttpError" // unexpected http response status code from server SherpaNoAPI = "sherpaNoAPI" // no API was found at this URL )
Errors generated by clients
const ( SherpaBadRequest = "sherpaBadRequest" // error parsing JSON request body SherpaBadParams = "sherpaBadParams" // wrong number of parameters in function call )
Errors generated by servers
const (
SherpaBadFunction = "sherpaBadFunction" // function does not exist at server
)
Errors generated by both clients and servers
const SherpaVersion = 0
Sherpa version this package implements. Note that Sherpa is at version 0 and still in development and will probably change.
Variables ¶
This section is empty.
Functions ¶
func Documentor ¶
func Documentor(docSrc io.ReadCloser, err error) (func() *Docs, error)
Documentor turns a documentation source (JSON file containing Docs) into a function returning those docs, parsed. This function is suitable for use as a "_docs" function.
func NewHandler ¶
func NewHandler(path, title, version string, functions map[string]interface{}, collector Collector) (http.Handler, error)
NewHandler returns a new http.Handler that serves all Sherpa API-related requests.
path is the path this API is available at. title should be a human-readable name of the API; if empty, a title is made of the last element from path. version should be an x.y.z string. functions are the functions you want to make available through this handler.
This handler strips "path" from the request.
Parameters and return values for exported functions are automatically converted from/to JSON. If the last element of a return value (if any) is an error (i.e. has an "Error() string"-function), that error field is taken to indicate whether the call succeeded. Exported functions can also panic with an *Error to indicate a failed function call.
Variadic functions can be called, but in the call (from the client), the variadic parameter must be passed in as an array.
Types ¶
type Client ¶
type Client struct { BaseURL string `json:"baseurl"` // BaseURL the API is served from, e.g. https://sherpa.irias.nl/example/ Functions []string `json:"functions"` // Function names exported by the API Id string `json:"id"` // Short ID of the API. May be nil. Title string `json:"title"` // Human-readable name of the API. May be nil. Version string `json:"version"` // Version of the API, should be in the form "major.minor.patch". May be nil. SherpaVersion int `json:"sherpaVersion"` // Version of the Sherpa specification this API implements. May be nil. }
Sherpa API client. If the API was initialized with a non-nil function list, some fields will be nil (as indicated).
type Docs ¶
type Docs struct { Title string `json:"title"` Text string `json:"text"` Functions []*FunctionDocs `json:"functions"` Sections []*Docs `json:"sections"` }
Documentation object, to be returned by a Sherpa API "_docs" function.
type Error ¶
Sherpa API error object. Message is a human-readable error message. Code is optional, it can be used to handle errors programmatically.
type FunctionDocs ¶
Documentation for a single function Name. Text should be in markdown. The first line should be a synopsis showing parameters including types, and the return types.
type InternalServerError ¶ added in v0.0.3
Error object that should propagate as internal server error (HTTP status 500). Useful for making Sherpa endpoints that can be monitored by simple HTTP monitoring tools.
func (*InternalServerError) Error ¶ added in v0.0.3
func (e *InternalServerError) Error() string
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
sherpadocs
Sherpadocs reads your Go source code and generates sherpa API documentation.
|
Sherpadocs reads your Go source code and generates sherpa API documentation. |