Simple HTTP RPC API's
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).
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.
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 sherpadoc.org can fetch and return any documentation for you. You can also call the functions on sherpadoc.org: it is also automatically an API playground.
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.
"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.
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.
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.
Not yet. It's on the to do list. Feel free to implement a mechanism and send it in!
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.
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.
Of course! (:
In fact, there are two good reasons to use old-fashioned RESTful endponts:
img tag.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.
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.
Yes. Just do a GET on a function and add the query string ?callback=... with a callback of your choosing.
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...
Of course! Suggestions, bug reports, patches, complaints, hugs, insights. All very welcome.
Use the following repositories:
Sherpa was created by Mechiel Lukkien, mechiel@ueber.net.