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


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:


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>
        .then(function(count) {
            console.log('successful result', count);
        }, function(error) {
            console.error('an error occurred', error.code, error.message);

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

/* To run this file as main.go:
go install bitbucket.org/mjl/sherpa/cmd/sherpadoc
sherpadoc Example > example.json
go run main.go
package main

import (

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

var count *int64

// 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)

// read documentation generated by sherpadoc
func readDoc() *sherpa.Doc {
    doc := &sherpa.Doc{}
    f, err := os.Open("example.json")
    if err == nil {
        defer f.Close()
        err = json.NewDecoder(f).Decode(doc)
    if err != nil {
    return doc

func main() {
    count = new(int64)
    handler, err := sherpa.NewHandler("/example/", "1.0.0", Example{}, readDoc(), nil)
    if err != nil {
    http.Handle("/example/", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))


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