API Usage Stories

The Mirror API provides a set of building blocks that you can use to build services for Glass. Because Glass services are probably different than other software you have developed, it may not be obvious how to fit features of the Mirror API together.

Many services fall into a few categories of API usage. Here are some stories that illustrate how to combine the features of the Mirror API to create Glass services.

Cat Facts

Delivering content to the Glass timeline is a simple yet powerful use of the Google Mirror API. The Cat Facts sample Glassware delivers facts about cats to users and could potentially follow this flow:

1. Your user visits your web application and subscribes by authenticating with OAuth 2.0.
2. Every hour, on the hour, your service delivers a new Cat Fact to each of your users' Glass.

Cat Facts would be implemented using the timeline insert method:

1. Users subscribe by authenticating with OAuth 2.0
2. Cat Facts stores an index of users and their credentials
3. Every hour, Cat Facts publishes a new Cat Fact. It does this by iterating through all stored users and inserting a timeline item into their timelines.

Add a cat to that

Each step in human technological advancement provides improved methods for the distribution of cat photos. Project Glass is no different.

Since every photograph is better with a cat, this service allows users to composite a random cat image and a photograph that they've taken with Glass.

1. Your user visits your web application and installs Add a Cat to That by authenticating with OAuth 2.0.
2. Your service creates a new contact on your user's Glass called "Add a Cat to That."
3. As your user takes photos, they share them with Add a Cat to That.
4. Your service composites a random image of a cat on to the shared photograph.
5. Finally, your service delivers the cat-enhanced photo to your user's Glass.

Architecturally, this service would follow this API flow:

1. Your user authorizes with OAuth 2.0. Your service stores their credentials.
2. Just after the OAuth 2.0 dance completes, your service inserts a contact called "Add a Cat to That".
3. Next, your service subscribes to updates in this user's timeline by inserting a subscription for the timeline collection. Add a Cat to That is now fully set up.
4. Over time, your user takes photographs.
5. Your user shares a photo with Add a Cat to That. This makes the timeline card associated with this photo accessible to your service.
6. Because your service is subscribed to timeline updates, a notification is sent to your service. This notification links to the timeline item containing the shared photo.
7. Your service examines the notification and uses the included id to fetch the timeline card that contains the photo.
8. Next, your service examines the timeline item and uses the attachment ID to fetch the bytes of the photograph.
9. Your service selects a random image of a cat, and composites it into the shared photograph.
10. Finally, your service constructs a new timeline card and inserts it into your user's timeline card with the cat-enhanced photo attached.

Note: As an added silly bonus, you can add the SHARE built in menu item to the timeline card. This allows cat-enhanced photos to be shared with other services or repeatedly shared with Add a Cat to That to add multiple cats to a photo.

Nearby pet stores

There's only one thing better than facts about cats or pictures of cats, and that's actual, physical, furry cats. The Mirror API can make this easier by making sure you always know where the nearest pet store is.

Usage follows this flow:

1. Your user visits your web application and subscribes by authenticating with OAuth 2.0.
2. Your service determines the user's location.
3. Your service searches for pet stores near that location.
4. Your service inserts a card to the left of the clock that lists these nearby pet stores.
5. Glass notifies your service about your user's location.
6. For each notification, your service repeats the pet store search and updates the pinned card to reflect the new set of nearest pet stores.

Implementing this service follows this API flow:

1. Your user authorizes with OAuth 2.0. In addition to the usual glass.timeline scope, your application also requests the glass.location scope access.
2. Just after the OAuth 2.0 dance completes, your service subscribes to updates on your user's location.
3. Next, your service fetches your user's latest location from the location endpoint.
4. Your service searches for pet stores near your user.
5. Your service creates a timeline card that lists the pet store search results. To keep this card on the left side of the clock screen, your service pins this card.
6. As your user moves around, their latest location is updated.
7. Because your service is subscribed to location updates, a notification is sent to your service. This notification links to the latest item in the location collection.
8. Based on the notification, your service fetches your user's latest location from the location collection.
9. Next, your service searches for pet stores near your user.
10. Finally, your service uses the patch method to update the body of the timeline item inserted in step 5.