One of the first things to get out of the way: the pico API is not RESTful. Picos don't present a collection of resources to be manipulated by GET, POST, PUT, and DELETE. However, the API does rely on HTTP and its methods for transport. If you've gotten REST as a religion, this may seem like sacrilege, but it's really a matter of using the right API for the job. RESTful APIs are great for request-response style interaction, but not so good for the evented interactions that picos support.
Instead, the pico API more closely follows the Command Query Separation (CQS) pattern, although there are no "commands" as such. Rather there are events. So, we might call it an event-query model. CQS provides for Command Query Responsibility Segregation. What this means is that the code stack that supports handling queries can be separated from code that supports modifying system state. Picos do this naturally as we'll see below.
Second, as I pointed out in Protocols and Metaprotocols, the pico API is really a meta-API in that describes the pattern for the API rather than the specific API itself. Put another way, every pico exposes a unique API depending on what rulesets have been installed in it.
The Sky Event API describes the event API pattern for a pico including what components are important and how those components are encoded in an HTTP method (GET or POST). The specific API for a given pico, however, depends on which rulesets are installed since it is rules that respond to events. Because of the event expressions in
select statements, we can calculate the specific events to which a given ruleset responds. This is called salience data. This is similar to the way that RMI uses Java classes to determine the specification for the object method interactions to which a particular Java class will respond.
Similarly, the Sky Cloud API defines the patterns for queries that a pico understands. Again, this is a meta-API, since the queries that any given pico responds to depend on the modules installed. Queries are thus implementable with different code than the event processing and, in practice, tend to be much faster.
The following diagram shows the event-query model and how applications use it.
In the systems we're building now, picos won't be created as empty vessels waiting for rulesets and modules to be installed and their API to be defined. Instead, we will have a way to create picos of specific types that come pre-loaded with rulesets that implement Wrangler and other services. Thus, when you'll create a pico to represent a vehicle, it will come with the event-query API as well as rulesets that provide a more specific vehicle collections event-query API along with a pre-defined data schema. This makes picos very powerful and gives developers significant leverage.
The event-query API model is a significant paradigm shift for Web developers. You have to throw out some of your old assumptions and remember, you're not building a Web application or using a RESTful API. A better analogy is to think of picos as cloud-based, persistent objects and model your application in the same way you would in an object-oriented programming language. In return you'll be rewarded with a different and interesting way to build Internet applications that scale well, can be distributed across multiple domains, and put users in control of their data.