mjl > sherpa intro
Intro | API documentation | Consuming | Specification | Implementations | FAQ | Why

Sherpa

Sherpa is a simple protocol for creating web API's with a specification and has implementations in several languages.

Why sherpa?

It's simple for:

Comparison

REST JSON-RPC gRPC Sherpa
Maps naturally to backend code No Yes Yes Yes
Self-describing No No Yes Yes
Includes documentation No No No Yes
Optimized for speed No No Yes No
Easy to use in frontend code No Yes No Yes
Everyone does it Yes No No No

Quickstart - Examples

Call function of existing sherpa API in web app:

<script src="https://www.sherpadoc.org/example/sherpa.js"></script>
<script>
    example.requestCount()
        .then(function(count) {
            console.log('successful result', count);
        }, function(error) {
            console.error('an error occurred', error.code, error.message);
        });
</script>

Export a sherpa API called Example, with a function requestCount, using the Go library:

/*
Run:
	go get github.com/mjl-/sherpadoc/cmd/sherpadoc
	sherpadoc Example > example.json
	go run main.go
*/
package main

import (
    "encoding/json"
    "log"
    "net/http"
    "os"
    "sync/atomic"

    "github.com/mjl-/sherpa"
    "github.com/mjl-/sherpadoc"
)

var count int64

// This is the API. These comments are added to the documentation by sherpadoc.
type Example struct {
}

// Count the number of requests. This comment and the function signature are
// automatically added to the documentation.
func (Example) RequestCount() int64 {
    return atomic.AddInt64(&count, 1)
}

func check(err error, action string) {
    if err != nil {
        log.Fatalf("%s: %s", action, err)
    }
}

func main() {
    // Read the API documentation generated by sherpadoc.
    var doc sherpadoc.Section
    f, err := os.Open("example.json")
    check(err, "open sherpadoc")
    err = json.NewDecoder(f).Decode(&doc)
    check(err, "parsing sherpadoc")
    f.Close()

    handler, err := sherpa.NewHandler("/example/", "1.0.0", Example{}, &doc, nil)
    check(err, "new sherpa handler")
    http.Handle("/example/", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

More

Learn more from the frequently asked questions.
Read why sherpa was created.