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, id, title, version string, functions map[string]interface{}) (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. id is the variable name for the API object the JavaScript client library. title should be a human-readable name of the API. functions are the functions you want to make available through this handler.
This handler expects to be called with any path elements stripped using http.StripPrefix.
If the last 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. 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.
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. |