One word: Simplicity.
Sherpa gets rid of a lot of dead weight. Let's do a comparison.
Consider writing a Sherpa API: You just write functions you want to export from your API. Then you simply call those functions from JavaScript. No need to write a client library: it's automatic. Documentation? Just write comments or annotations in your code and you have API documentation! You also automatically get a playground to try the API functions.
REST API's are a popular option for making web API's. I've created plenty myself. It's goes a little like this: Specify data model, find a way to map the data onto URLs (you'll have to shoehorn it, it's never quite the natural fit). Next: determine what all the HTTP stuff is supposed to do on your URLs:
I'll summarize: lots of time spent on little. It's because REST is pretending to be modelling data (but not actually helping you with that!), while it is really just a very complex and crappy RPC mechanism. No more! Let's stop pretending and get rid of that needless complexity!
Sherpa API's are function-oriented. Similar to JSON-RPC. But Sherpa API's have two main advantages. See below. There are older and other mechanisms like XMLRPC (you don't want XML in your web app), and SOAP (XML and also complicated on its own), and gRPC (can't call it from your browser). Sherpa's advantages:
This is not revolutionary. It's just a simple mechanism that needed to be created.
Unfortunately, REST is often used when these are not needed, making API's much more complicated or undocumented and undiscoverable than necessary. But, REST is useful in a few situations:
One of the main features of REST API's is cachability of responses. This allows for scalability: fewer requests at the server. This is indeed great. However, in practice, for most REST endpoints you'll disable caching. You do this to prevent your web app from displaying stale data. Only if you have explicitly designed endpoints for caching, should you enable it by setting the right headers. So, for the cases where you really need cacheable responses, create an endpoint outside of the Sherpa API.
With RESTful API's, you can have endpoints that return images. Very practical, because it allows you to use a simple HTML img tag to display such images. If you need such endpoints — so when you really aren't doing a remote procedure call — create them outside of the Sherpa API.
REST appears to have some magical properties. Nearly everyone is enchanted by REST. "REST is good", seems to be the consensus. Don't you see the complexities? Let's have a look.
It's often ambiguous how your data domain should be mapped to URL's. Should it be /api/v1/user/:id, or should it be /api/v1/group/:id/user/:id? It depends.
In the actual implementation of your REST endpoints, you'll usually map such URL templates to a function. That function is then called when a HTTP request comes in matching that URL pattern.
Sherpa doesn't have that URL-mapping part. It's just the function name that you cared about. Simpler. Better.
RESTful-fans seem to think HTTP must be used to its fullest extent. First, granted, HTTP has been great for the internet. Second, HTTP also has plenty of flaws, is quite complex, and has features that don't really work nicely with eachother. "Using HTTP" gives a false impression of compliance. Does your REST API handle Accept or If-Modified-Since headers properly? Is it prepared to handle one of the many other headers that HTTP clients might throw at it? Probably not.
Sherpa simply skips nearly all the HTTP complexity. Simpler. Better.
Part of designing REST API's involves specifying the semantics the various HTTP methods have on your endpoints. Some HTTP methods might not be supported, you have to document that. The same goes for HTTP status codes. You have to specify which you're going to send. It's usually semi-standard among REST API's, but implementations don't all go to same (proper & complicated) lengths to respond with the "right" HTTP status codes.
What should a client library do when it receives a status "200" for creating an object with a POST (where "201" would be expected)? Is that an error from the API? Should the client library take that as a sign the object already existed? HTTP status codes for RESTful operations often confuse more than they clarify.
Sherpa simply uses HTTP as a transport, not caring for status codes. Simpler. Better.
With REST, you think you're modelling your data as URL's. You'll probably return objects as JSON. But pretty soon you'll turn your endpoints into remote procedure calls. Don't believe? I'll explain.
If you're building an app that must list tables full of data, you'll need pagination. You cannot just return all millions of objects when a client requests a (hypothetical) imdb.com/api/movie. So you add query string parameters than handle pagination. And filtering. And sorting. So what is that endpoint representing? Not just data. It's just some sort of method for looking at data. And a pretty lousy one at that. You can put all kinds of parameters and hints in query string parameters, and headers. REST API's will usually ignore most of that stuff, until they don't...
With Sherpa, you skip all that pretending, and realize you just want to call remote functions. Simpler. Better.
REST API's are not easy to start using from JavaScript. How would you list which endpoints exist? With URL templates that include strings like "/:id/"? How do you start using the API? Probably you'll start by just creating URL's in JavaScript and fetching data. Maybe with jQuery.getJSON. This works for a while. But pretty soon you'll want to automate some of that. And you'll write a client library for your specific REST API. Lots of wasted energy.
With Sherpa, every API has a (JavaScript) client library automatically. You just call functions from an API object. Simpler. Better.
REST API's are relatively hard to document. Each endpoint has multiple dimensions for which behaviour has to be documented:
So how do you actually document REST API's? Well, you might use RAML. Or Swagger. Most of the complexity of those tools is for specifying all the dimensions listed above. That's a lot of work for very little gain.
With Sherpa, you just write comments or annotations for your functions, and you automatically get live-rendered documentation. Simpler. Better.
One of the most important features of the "web" is linkability. Any page can link to any other page. It would be great if we could do the same with data. REST has a vague promise of doing that. And you can indeed write down a URL that represents some piece of data. Unfortunately, that doesn't say anything about the response formats that endpoint can return, or which additional query string parameters it understands (like for filtering or sorting). In practice, you cannot automatically do much with data from a REST API.
REST API's sometimes use URI's as "id" fields for objects. In theory, you could assume that URI would then support a DELETE, PUT and PATCH method. In practice, you wouldn't automatically know the semantics of such calls. Another problem with this kind of linkability is collections. Say you get a list of objects that point to (reference) other objects, by URI. How would you then efficiently fetch those objects? Simply do N GET requests, one for each unique URI? What if there are hunderds? That's why you will create REST API endpoints that will return objects for a whole bunch of "id"'s. And then you realize you've simply created a (very complex) RPC mechanism. You don't have to learn this the time-consuming way. Just use Sherpa. Simpler. Better.
To keep it short:
Luckily there is also:
Why Sherpa? Simpler. Better.
Save yourself time, and realize most uses of "REST" are actually remote procedure calls. And that Sherpa is a better RPC mechanism. You'll benefit from API discovery, built-in documentation and immediate JavaScript libraries. Only use REST when browsers are sending requests directly, or when your data must actually be cacheable.