How does it work?
The Realtime API is based on the same collaboration technology used by Google Docs. Whenever a collaborative data model is modified, the change is applied immediately to the local, in-memory copy of the document. The API then silently sends a representation of the change to the server (called a "mutation") so that the change can be recorded in the document and communicated to other collaborators. The mutations have been carefully designed so that conflicts between collaborators can always be automatically resolved, so users will never have to see a message about edit conflicts.
Realtime data models are "eventually consistent." That means that if all collaborators stop editing, eventually everyone will see the same data model. However, we make no guarantees about when all the collaborators will see the changes or what order the changes will be delivered in.
What is the Realtime API good for?
Applications where multiple people need to edit the same data simultaneously. Document editors are excellent examples of this kind of application.
What is the Realtime API not good for?
Applications where multiple people need to edit the same data in a particular order. A board game is an example of this kind of application, where changes from users need to occur in a particular order. This kind of app is very, very difficult to write using the Realtime API because, by design, at any given moment it's impossible to know whether other collaborators have made changes to the document.
What does the Realtime API do for me?
The Realtime API handles all aspects of data transmission, storage, and conflict resolution when multiple users are editing a file. Specifically, it provides:
- Functions to load and work with Realtime documents.
- Built-in collaborative objects (strings, lists, and maps).
- The ability to create your own custom collaborative objects.
- Events for detecting changes to the collaborative model or collaborators joining or leaving the document.
- A text binder for binding collaborative string objects to the DOM.
The Realtime API provides all the tools you need to create a fully collaborative application without running your own server.
What doesn't the Realtime API do?
The primary goal of the Realtime API is to handle the heavy lifting of implementing realtime collaboration so you can focus on building your app. The Realtime API is designed to work with other APIs such as the Drive and OAuth APIs to handle functionality not directly related to collaboration. Examples of tasks that are not handled by the API include:
- Converting to/from binary formats—These are the responsibility of the app.
- Reading/writing to files—This is already handled by Drive.
- Model locking—Drive already supports a last-write-wins consistency model.
The Realtime API, combined with the Drive and OAuth APIs, provides everything you need to create a fully functional collaborative app, leaving you free to focus on the application-specific logic.
Lifecycle of a Realtime App
In a typical scenario a Realtime application will:
- Enable the Drive API
- Load the Realtime library
- Authorize requests
- Open/create a file
- Load a document and initialize the data model
- Make changes/listen for changes on the data model
Watch the video overview
The video from the Google I/O session provides a brief overview of how the Realtime API works and what you can do with it. If you'd like to learn what the Realtime API is with a demonstration and some tips directly from the developers, click play, sit back, and enjoy.