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


Every sherpa API comes with its own tiny, automatically generated, standalone JavaScript library that makes it trivial to start using that API from a browser.

Especially for small or internal projects, where you create both the backend and the frontend code, this is all you need to create a web app.

If a sherpa API lives at https://www.sherpadoc.org/example/ (try it!), just add "sherpa.js" to load the library: https://www.sherpadoc.org/example/sherpa.js. It exports an object "example" and contains all exported functions and a field "_sherpa" with basic information about this sherpa API. The functions can be called and will return a "thenable": An object on which you can call ".then()" to register a success and error handler.

On success, your success handler will be called with a single value: whatever the server returned. It's always a single value, functions that return multiple values will have a JavaScript array as a result.

On error, you error handler will be called with an error object. This object contains a field "code" (a string, to be used in your error handler, the API documentation will explain which errors can happen), and a field "message" (human-readable, for display to the end-user).

Note: Thenable are not full promises. Not all browsers support promises natively. However, you can easily turn sherpa's thenable into promises (or something similar): Set the variable "_wrapThenable" on the sherpa API object to a function that takes a thenable as parameter, and that returns a promise(-like) object of your choosing. For example, your function could return "new Promise(thenable)", or if you use angularjs, you can add a line "example._wrapThenable = $q;".

That's all you need to know for a quick JavaScript web app.

Using external sherpa API's

If you need to use a sherpa API from JavaScript that someone else provided, you probably don't want to load their JavaScript. For this use case, a standalone sherpa JavaScript library is available. See github.com/mjl-/sherpajs.

Typescript with "sherpats"

Sherpa documentation now contains type information about parameters/return values of API functions. You can use this type information to generate a typescript library that exports those functions along with their types. This lets you typesafely use a sherpa API. Sherpats is the tool that reads sherpadoc and writes a typescript module.

sherpats < example.json > example.ts

Other languages

Want to consume a sherpa API from another language? Have a look at the list of sherpa implementations.