README
¶
Sherpa is a library in Go for providing and consuming Sherpa API's.
The Sherpa specification can be found at:
https://www.ueber.net/who/mjl/sherpa/
This library makes it trivial to export Go functions as a Sherpa API, including documentation.
Use the sherpaweb tool to read API documentation and call methods (for testing purposes).
Use the CLI tool sherpaclient to inspect API's through the command-line:
# the basics of the API
$ sherpaclient -info https://sherpa.irias.nl/example/
# call a function
$ sherpaclient http://localhost:8080/example/ echo '["test", 123, [], {"a": 123.34, "b": null}]'
["test",123,[],{"a":123.34,"b":null}]
# all documentation
$ sherpaclient -docs https://sherpa.irias.nl/example/
...
# documentation for just one function
$ sherpaclient -docs https://sherpa.irias.nl/example/ echo
...
Use the CLI tool sherpadocs to generate Sherpa documentation from the comments in the Go source files.
$ sherpadocs path/to/myapi 'My API' 'goFunctionName:sherpaFunctionName,...' >myapi.json
See https://bitbucket.org/mjl/sherpaweb/ with its Example API for an example.
Documentation
https://godoc.org/bitbucket.org/mjl/sherpa
Compiling
go get bitbucket.org/mjl/sherpa
About
Written by Mechiel Lukkien, [email protected]. Bug fixes, patches, comments are welcome. MIT-licensed, see LICENSE.
todo
-
on errors in handler functions, it seems we get stack traces that are very long? is this normal?
-
check if we need to set more headers, and if cors headers are correct
-
allow more fields in error response objects?
-
more strict with incoming parameters: error for unrecognized field in objects
-
sherpadocs: attempt to automatically generate the synopsis line?
-
sherpadocs: investigate if struct definitions can be used in docs
-
say something about variadic parameters
-
handler: write tests
-
handler: write documentation
-
handler: run jshint on the js code in sherpajs.go
-
client: write tests
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.
Source Files
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. |