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



What does Sherpa mean?


Are Sherpa API's RESTful?

Not really. REST API's take a data-centric approach. They try to model the data on URL's, and use HTTP methods to model operations. Sherpa API's take a function centric approach, just like JSON-RPC and (a longer time ago) XMLRPC. Sherpa API's takes away all the trouble of coming up with proper URL mappings, HTTP method mappings and header intricacies (typically simply ignored by REST API designers).

How does Sherpa do API versioning?

The version of Sherpa specification an API implements is supplied in the API descriptor (sherpa.json). A Sherpa API itself also has a version number, that is loosely interpreted as major.minor.patch. If you make incompatible changes to a Sherpa API, you should probably publish it under a new endpoint. Since implementing an API is very easy with Sherpa, this is a feasable approach.

With REST, some people put a version number in the URLs. This is not really RESTful, it could mean a single object can have multiple URI's. This is usually the best approach in practice though. However, since REST API's are relatively time-consuming to write, you probably won't easily bump the version number.

How do you document a Sherpa API?

Documentation is a strength of Sherpa API's. Depending on your programming language, and sherpa library, you either write regular comments for your sherpa-exported functions, or add annotations to your code. Sherpa library then provide a function named _docs that returns a simple JSON document containing part structured documentation, part markdown.

The tool sherpaweb, publicly available at sherpa.irias.nl can fetch and return any documentation for you. You can also call the functions on sherpa.irias.nl: it is also automatically an API playground.

Does Sherpa cache responses?

No, Sherpa does not. All client-side API calls will result in a HTTP request. An API is free to cache results and return them in later requests. And an API is free to document that some function results can be cached by a client. But this is not built into Sherpa API's.

So will Sherpa API's be scalable?

"Caching is a way to make web API's scalable. If Sherpa doesn't return cacheable response, how can you make scalable API's?"

Well, you use as many servers as you need to serve the HTTP requests. You can still do caching in your backend, which you are probably doing already if you have a web service that needs to be "scalable". So nothing new really.

Does Sherpa provide a standard way to filter/sort/paginate data?

No. Just like REST API's don't. Maybe Sherpa can prescribe useful mechanisms for these in the future. Right now, you explicitly need to pass such query parameters in the Sherpa API calls. At least that makes them implicit. As opposed to the easy-to-get-wrong-and-subsequently-ignored query string parameters in most REST API's.

How do I model error messages in Sherpa?

It's about time you start reading the specification! To summarize: A call results in a JSON body with either a results-field on success or an error-field on failure. The error field can be filled with an object with a human-readable error message in the message field, and an optional programmer-usable error code (a string) in the code field.

Can I call multiple Sherpa function in a single HTTP request?

Not yet. It's on the to do list. Feel free to implement a mechanism and send it in!

Why are function names part of the URL?

In an early draft of Sherpa, they weren't. Like in JSON-RPC, they were part of the request body. However, that's not very convenient to web developers. With function names in the URLs, it's easy to see which functions are being called in browser developer consoles that show HTTP requests.

Does Sherpa support server-sent events or websockets?

Not yet. For now it's best to create separate HTTP endpoints for such services. You could still explain and point to them using Sherpa documentation. Perhaps in the future it'll be part of Sherpa, but they may stay too dissimilar to normal remote procedure calling.

Can I still use RESTful endpoints when using Sherpa?

Of course! (:

In fact, there are two good reasons to use old-fashioned RESTful endponts:

Does Sherpa provide an authentication mechanism?

No. You could use JSON web tokens. Or even HTTP basic/digest auth (over HTTPS). Authentication is too broad a subject to put into Sherpa.

Does Sherpa support a HTTP GET to call a function?

Yes. Just do a GET instead of a POST on a function. You can pass parameters in the regular JSON format, but you must pass the JSON body (properly URL-escaped) in a query string parameter called body.

One of the reasons is that it makes uptime monitoring tools easier to use: Just pass them a URL they will GET. It also makes passing around example URLs for APIs a bit easier.

Does Sherpa support JSONP?

Yes. Just do a GET on a function and add the query string ?callback=... with a callback of your choosing.

How should I implement file uploads?

Sherpa doesn't prescribe any way to handle file uploads. In practice, it's often good enough to just data-URL encode file uploads and put that inside JSON. It's not ideal: the file sizes become larger (due to base64 and absence of gzip while uploading). Sherpa might need a better scheme in the future...

Why aren't parameter and return types part of function signatures?

First, dynamic languages (eg JavaScript) don't need or make use of such type information. Requiring type specification could become too much of a burden.

Second, the Sherpa specification, and its implementations, would become much more complicated. It's not the sweet spot Sherpa is aiming for.

Shouldn't Sherpa provide mechanisms for structuring documentation better?

Sherpa allows writing documentation per API section, and per function within each section. This documentation is in markdown. This lets you created tables, bullet points, links, etc. You can also provide further visual structure by using HTML. There is no structured way to indicate which error codes can be returned, or whether a function requires authentication (as defined by your API), or to show example parameters and an example response. When the need is strong enough, it'll be added.

Can I contribute?

Of course! Suggestions, bug reports, patches, complaints, hugs, insights. All very welcome.

Use the following repositories:

Who created sherpa?

Sherpa was created by Mechiel Lukkien, mechiel@ueber.net.