About the APIs

The PureWeb APIs is what enables thin clients on end user devices to interact remotely and seamlessly with powerful, resource-intensive visualization software.

The APIs use the native syntax of the target platform, which is why you need one for your service (C++, .Net or Java) and a different one for your client: HTML5 (JavaScript), iOS (Objective-C/Swift), or Android.

When you develop your PureWeb solution, you use the service and client APIs in parallel, for example:

  • The service API provides methods for streaming images, and the client API provides the means to display the streamed images,
  • The client API captures user input within views, and the service API provides handlers where you can write the logic for responding to these events.

One of the key features of the APIs is that they remain largely independent of the application logic, Rather, they simply add a thin layer of API calls (new event listeners and handlers, new functions as needed, and so on). When using PureWeb to modernize an older application, this is a very significant advantage, since you can leverage your existing code with minimal changes.

PureWeb APIs have three central pillars: views, application state, and commands.


Views

Views are the backbone of the client user interface. You use them to display graphics rendered by the service application as interactive images on client devices.

Views should not be confused with screen scraping. They are typically used to stream the 2D or 3D visualizations rendered by the service, but in a broader sense, they can be used to display any image data (bitmap). You can display several views on the screen at once.

The process for streaming graphics using views is relatively straightforward: on the service, you register a view with a given name, then implement an interface containing a method which is called by PureWeb every time it wants to update the view. This method provides a parameter which you populate with the bitmap image data to send. PureWeb takes care of the rest (see Stream graphics from the service). On the client, you create a container for the view, then instantiate the view with the name you provided on the service (see Display views on the client).

Once the view is displayed in the client, user input events are automatically captured and delivered to the service, where you can decide what to do with them (see Respond to user input in views). Other API methods allow you to ensure views are updated with new images as needed, and to keep view sizes in sync, when users rotate their device, for example.

PureWeb takes care of the technical intricacies of the imaging pipeline in the background (image scaling, colorspace conversion, noise reduction, data compression, and so on). But you have control over the image encoding, and can change the configuration to strike the optimal balance between image quality and system performance. You can choose different encoding settings for different clients, for different views within a client, and even for different interactivity modes within a view (see Fine-tune the image encoding).

In collaboration scenarios, when multiple clients are connected to a single service, the views on that service are available to all clients. Each client gets a copy of each view and can interact with each view independently (see Use the built-in collaboration feature).


Commands

Commands are simple instructions sent from the client for the service to execute a given function. For example, if your application has a search feature, you could create an input field in the client and use a command to trigger the search on the service when the user clicks the search button. In a similar fashion, you can use commands to handle touchscreen input (the Scribble sample application provides an example of this, by using commands to clear the screen when the user shakes the device).

Commands are event-based. Implementing them is straightforward: you create a function in your client to send the command, and you create a handler in your service to respond to the command (see Set up a basic command).

Commands may include parameters and a callback. For example, if you send a command to perform a search, you can provide the search parameters in the command call on the client, and populate the search results in the command response from the service (see Work with command parameters). The search results would then be available to the command callback if you specify one (see Work with command callbacks).

There are some situations where commands are not suitable:

  • Commands are event-based; for information which is really stateful and doesn’t have the characteristics of an event, you would use application state.
  • Commands are only sent from a single client to the service, and the service will return the response only to the client who originated the command. For collaboration scenarios where information needs to be communicated to all connected clients, you would use application state.

Application state

Application state is a hierarchical tree of properties and values which resides on both the service and the client. PureWeb uses it under to hood to store properties that it needs to make the solution work, such as session IDs, and to maintain state synchronicity. Whenever state changes occur, on either the service or the client, it automatically transmits the differences to the other side (see Explore the organizational structure of application state). These differences are then merged into the local application state, bringing both client and service states into sync.

You can store your own user-defined elements in application state, and you can take advantage of this to integrate service functionality into the client. For instance, you could store the state of a checkbox in application state. Then, when the user selects the checkbox in the client, you could change its state to "selected", which would notify the service to trigger the functionality of that checkbox. The APIs provide methods for getting and setting state values, or groups of values, and allow you to register handler functions that are called when a single value or an entire section of application state changes (see Set up change handlers).

Application state can also be used as a simple data store. For instance, you could use it to store usernames, URLs, the level reached by a player in a game, or anything else that can be expressed as an XML element or collection of elements. There is one caveat, however: all clients connected to the service have access to all data in application state. For maintaining private synchronized data stores individually for each user session, you would use a different feature called Session Storage.

<ApplicationState xmlns:typeless="http://calgaryscientific.com/typeless/2008">
    <PureWeb>
        <Application>ScribbleApp</Application>
        <InteractiveQuality>30</InteractiveQuality>
        <FullQuality>70</FullQuality>
        <Sessions>
            <SessionId-01000000-0000-0000-0000-000000000000 />
        </Sessions>
        <Collaboration>
            <OwnerSession>01000000-0000-0000-0000-000000000000</OwnerSession>
            <Sessions>
                <SessionId-01000000-0000-0000-0000-000000000000>
                    <DefaultColor>#FFFF0000</DefaultColor>
                    <UserInfo />
                </SessionId-01000000-0000-0000-0000-000000000000>
            </Sessions>
        </Collaboration>
    </PureWeb>
    <ScribbleColor>White</ScribbleColor>
</ApplicationState>

Application state and commands are often combined together to create some really useful features. For example, you could use a command to tell the service to capture the screen, save it to the local file system, then tell the service API to generate a URI to the image; by storing the URI in application state, you would enable all of the collaborating clients to download the saved screenshot for later use.


The first API method call when creating your PureWeb application must be to instantiate the StateManager class in your service, so that it can talk to the PureWeb server. See First steps.