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 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.
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
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:
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...
Second, the Sherpa specification, and its implementations, would become much more complicated. It's not the sweet spot Sherpa is aiming for.
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.
Of course! Suggestions, bug reports, patches, complaints, hugs, insights. All very welcome.
Use the following repositories:
Sherpa was created by Mechiel Lukkien, firstname.lastname@example.org.