mjl > sherpa > sherpa.js
Intro | API documentation | sherpa.js | Libraries | Specification | Why | FAQ

sherpa.js

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://sherpa.irias.nl/example/ (try this link!), just add "sherpa.js" to load the library: https://sherpa.irias.nl/example/sherpa.js. It exports an object "example" (named after the last element in the path of the URL) 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 the average web app.

Using external sherpa API's

If you need to use a sherpa API 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 sherpa.js. It is part of sherpaweb, the tool you use to read sherpa API documentation. After including this library, you can get a sherpa api object:

var api = sherpa.init(baseURL, _sherpa)

Where baseURL could be "https://sherpa.irias.nl/example/" and _sherpa would be the content previously loaded from baseURL/sherpa.json.

Alternatively, you can get a promise that resolves to an API object by calling:
sherpa.load(baseURL)

Example of sherpa.init

This is a fully functional example of using sherpa.init:

<script src="https://sherpa.irias.nl/s/js/sherpa.js">
<script>
var example = sherpa.init('https://sherpa.irias.nl/example/', {functions: ['requestCount']});

example.requestCount()
.then(function(result) {
	alert('Number of requests: '+result);
}, function(error) {
	alert('Error: '+JSON.stringify(error));
});
</script>

Example of sherpa.load

And this is how you use sherpa.load:

<script src="https://sherpa.irias.nl/s/js/sherpa.js">
<script>
sherpa.load('https://sherpa.irias.nl/example/')
.then(function(example) {
	example.requestCount()
	.then(function(result) {
		alert('Number of requests: '+result);
	}, function(error) {
		alert('Error: '+JSON.stringify(error));
	});
}, function(error) {
	alert('Error loading API: '+JSON.stringify(error));
});
</script>