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 sherpaweb 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 -doc https://sherpa.irias.nl/example/
...
# documentation for just one function
$ sherpaclient -doc https://sherpa.irias.nl/example/ echo
...
Use sherpadoc to generate Sherpa documentation from the comments in the Go source files.
$ sherpadoc Example >example.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
-
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.
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. An example of how to use NewHandler can be found in https://bitbucket.org/mjl/sherpaweb/
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 NewHandler ¶
func NewHandler(path string, version string, api interface{}, doc *Doc, 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. version should be of the form x.y.z. api should by a struct. all its methods are exported as functions. all fields must be other sections (structs) whose methods are also exported. method names must start with an uppercase character to be exported, but their exported names start with a lowercase character. doc should be sherpa documentation as generated by sherpadoc.
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 Doc ¶ added in v0.3.0
type Doc struct {
Title string `json:"title"`
Text string `json:"text"`
Functions []*FunctionDoc `json:"functions"`
Sections []*Doc `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 FunctionDoc ¶ added in v0.3.0
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
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
sherpaclient
Sherpaclient calls Sherpa API functions and prints Sherpa API documentation from the command-line.
|
Sherpaclient calls Sherpa API functions and prints Sherpa API documentation from the command-line. |
|
sherpadoc
Sherpadoc reads your Go code, and prints sherpa documentation in JSON.
|
Sherpadoc reads your Go code, and prints sherpa documentation in JSON. |