README
¶
Sherpa is a Go library for creating Sherpa API's.
This library makes it trivial to export Go functions as a Sherpa API with an http.Handler.
API you create will automatically be documented: The sherpadoc command reads your Go source, and exports function and type comments as API documentation.
Sherpa
Sherpa is a simple mechanism for providing web API's, typically for creating web applications and providing fully documented API's at the same time. Details:
https://www.ueber.net/who/mjl/sherpa/
Examples
A public sherpa API:
https://sherpa.irias.nl/#https://sherpa.irias.nl/example/
That web application is sherpaweb. It exports an API called Example. The code for sherpaweb is available at:
https://bitbucket.org/mjl/sherpaweb/
Look for "type Example" and "type Signatures" for the API implementation. Sherpaweb is a web application that lets your "discover" (read docs and call functions) any sherpa API your browser can connect it, including your local development environment.
A more elaborate web application built on a Sherpa API:
https://github.com/irias/ding/
Documentation
https://godoc.org/bitbucket.org/mjl/sherpa
About
Written by Mechiel Lukkien, [email protected]. Bug fixes, patches, comments are welcome. MIT-licensed, see LICENSE.
cmd/sherpadoc/gopath.go originates from the Go project, see LICENSE-go.
todo
-
handler: write tests
-
sherpadoc: write tests
-
client: write tests
-
when reading types from other packages (imported packages), we only look at GOPATH. vendor and modules are not taking into account, but we should.
Documentation
¶
Overview ¶
Package sherpa exports your Go functions as fully documented sherpa web API's.
Sherpa is similar to JSON-RPC, but discoverable and self-documenting. Read more 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/
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
SherpaVersion is the version of the Sherpa protocol this package implements. Sherpa is at version 0, still in development and may change.
Variables ¶
This section is empty.
Functions ¶
func NewHandler ¶
func NewHandler(path string, version string, api interface{}, doc *Doc, opts *HandlerOpts) (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 a semantic version.
API should by a struct. It represents the root section. All methods of a section are exported as sherpa functions. All fields must be other sections (structs) whose methods are also exported. recursively. Method names must start with an uppercase character to be exported, but their exported names start with a lowercase character.
Doc is sherpa documentation as generated by sherpadoc.
Opts allows further configuration of the handler.
Methods on the exported sections are exported as Sherpa functions. If the first parameter of a method is a context.Context, the context from the HTTP request is passed. This lets you abort work if the HTTP request underlying the function call disappears.
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, that error field is taken to indicate whether the call succeeded. Exported functions can also panic with an *Error or *InternalServerError to indicate a failed function call. Returning an error with a Code starting with "server" indicates an implementation error, which will be logged through the collector.
Variadic functions can be called, but in the call (from the client), the variadic parameters must be passed in as an array.
This handler strips "path" from the request.
Types ¶
type Collector ¶ added in v0.2.0
type Collector interface {
ProtocolError() // When a request is invalid at protocol-level, e.g. wrong mimetype or request body.
BadFunction() // When called function does not exist.
JavaScript() // When sherpa.js is requested.
JSON() // When sherpa.json is requested.
FunctionCall(name string, error bool, serverError bool, durationSec float64) // When function "name" is called, and whether that caused an "error" at all, and a "serverError" in particular, and how long the call took.
}
Collector facilitates collection of metrics. Functions are called by the library as such events or errors occur. See https://github.com/irias/sherpa-prometheus-collector for an implementation for prometheus.
type Doc ¶ added in v0.3.0
type Doc struct {
Title string `json:"title"` // Name of an API section.
Text string `json:"text"` // Explanation of the API in markdown.
Functions []*FunctionDoc `json:"functions"` // Documentation for each function exported in this API.
Sections []*Doc `json:"sections"` // Subsections, each with their own documentation.
}
Doc represents documentation about a Sherpa API, as returned by the "_docs" function.
type Error ¶
Error returned by a function called through a sherpa API. 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
type FunctionDoc struct {
Name string `json:"name"` // Name of the function.
Text string `json:"text"` // Markdown, describing the function, its parameters, return types and possible errors.
}
FunctionDoc contains the documentation for a single function. Text should be in markdown. The first line should be a synopsis showing parameters including types, and the return types.
type HandlerOpts ¶ added in v0.4.0
type HandlerOpts struct {
Collector Collector // Holds functions for collecting metrics about function calls and other incoming HTTP requests. May be nil.
LaxParameterParsing bool // If enabled, incoming sherpa function calls will ignore unrecognized fields in struct parameters, instead of failing.
}
HandlerOpts are options for creating a new handler.
type InternalServerError ¶ added in v0.0.3
InternalServerError is an error that propagates as an HTTP internal server error (HTTP status 500), instead of returning a regular HTTP status 200 OK with the error message in the response body. 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. |
|
Package sherpadoc is a library with a Main function so you can run it as a command during builds.
|
Package sherpadoc is a library with a Main function so you can run it as a command during builds. |