•
Sharendipity is proving to be one of the most dynamic (fantastic!) ways of consuming web services of all kinds. With built in support for RESTful web services, it becomes trivial to implement an interface for lots and lots of third party data sources.
When creators chose to share their implementations with the community, everyone gets an opportunity to leverage the web service without ever having to look at an API document. You can simply drag the service into your application and access the data by calling the respective method.
Most implementations available in the community today are returning the data gift wrapped for your enjoyment. For example, you can take advantage of the Facebook Services to access the profile data for all of your friends and it is given to you in a list of “Facebook User” objects. Poof! Your social graph is there for you and you never once went to the Facebook developer wiki!
Likewise, you can use the YouTube services to ask Google for every YouTube video uploaded by a particular user and are presented with a list of assets that not only tells you the URL but also all of the comments, ratings, description, related videos, etc.
As you might tell, I’m smitten with the power of the web services. The following is a sample of the variety of applications that are using web services today…
Most of these examples are application templates, which allow users to personalize the web service calls for their specific needs. For example, the Twitter/Last.fm application lets you configure a band or singer name for the chatter you’d like to display.
Every application comes with its own embed code so you can post it anywhere on the web.
Anyone can implement and share web services so if you haven’t found the service you’re looking for feel free to get started building your own components. You can read our how-to post if you need a primer to get started.
Tags:
web services,
widget
•
By combining the new YouTube video integration plus a user-defined implementation of the YouTube Data API, we were able to create miniature television sets that have custom channels!
Sure, YouTube lets you embed a video anywhere, but now you get to embed your own personalized TV channel with a long list of your favorite videos.
This post will document the components and techniques used to build this particular app. However, if you’d like to re-use this one and customize it for your own YouTube content, here are some shortcuts:
- User Channel – This version will let you play all videos uploaded by a particular YouTube user.
- User Favorites – This version will let you play all videos that have been marked as a “favorite” by a particular YouTube user.
- YouTube Search – This version will let you play all videos that match a particular search term.
- A single video – This version will let you play a single video, as defined by the YouTube video ID.
Anatomy of the TV
We’re going to break down this application to give you a better sense of how it was created and perhaps inspire you to create your great video app. This application has three basic elements:
- Pretty artwork!
- A video player object that plays video and responds to controller input
- User interface controls to start, stop, and change the channel for the TV
- A web service that locates the desired video and all of the related content
Pretty artwork
There is one large rectangle that has the television artwork applied to it. The artwork was created in such a way that the center (display) space was made transparent. This provides the ability to see other objects that have been placed in the background.
The artwork on the rectangle has been marked as “configurable” so other users can re-skin their televisions during the customization process. If you’d like to create your own skin for this particular television, create a jpeg or png that is 300 x 225. The transparent cutout should be 266 x 150 and offset from the top edge by 8 pixels. You can upload the skin during the customization.
Kudos to Man Vs. George Design studio for some handsome artwork!
YouTube video player
In the background, there is an object that displays the video. It’s nothing more than a rectangle that has some additional logic to control the playback features. As we discussed earlier, the key element to playing YouTube videos is through the manipulation of an object’s image property.
To simplify access to the video player’s properties, methods were defined on the object. This allows the application to manipulate the channel using higher level functions.
These four methods provide access to other objects in the application to control playback. But it lets the video player actor itself decide how to implement them. You can find this actor – “video player” – available in the asset manager to be used in your own application.
User interface controls
You’ll notice that there are several controls sitting on the lower portion of the television. These are just rectangles with artwork applied. They each have behaviors defined on them that declare what should happen when a mouse click occurs. Under the hood, they utilize the methods defined on the video player to manipulate the video.
The “?” button is slightly different. It creates a hover screen and displays some of the details for video that is currently being played (like name, play count, and average rating).
YouTube web services
Rather than simply specifying a single video for playback, this app leverages the YouTube web services objects to locate video streams for playback. This not only creates an opportunity to access limitless amounts of video content, but it also provides access to all of the video details including title, description, ratings, view counts, comments, etc. Anything you find on the video’s YouTube page, you can find in the web services. What awesome power!
Google provides access to this data via their YouTube Data API. Several of these API feeds have been implemented within Sharendipity. You can access them simply by dragging the definition types into your application. Just search the asset manager for “YouTube Service” and you’ll find several feeds under the “Types” category:
- Access to a user’s uploads
- Search by query terms
- Access a user’s “favorites” list
- Access to individual videos based on video ID
- Search by YouTube channel
All of these services return an array of YouTube data structures that describe all of the details of individual videos.
Is there a missing feed you need? Anyone can create these so feel free to jump in. Of course, if we can help, we’d love to hear from you.
New opportunities
We’re really excited about the potential with video. By providing access to Google’s Player API as well as the Data API – while abstracting away all of the programming – we think great things can be accomplished in gaming, marketing, as well as education.
Everyone has the opportunity to build engaging video content now. Go get started!
Tags:
API,
howto,
Tutorial,
web services,
YouTube
•
Several web service interfaces have been built and shared within the Sharendipity community including services for Facebook, Twitter, Flickr, Posterous, and Google Docs. Using these components you can quickly and easily access the data from these sites/services.
But what happens if you can’t find the service you’re looking for? Or if you want to improve on one of the existing services and make a better one yourself?
This post is here to help. We’ll walk you through some of the basic elements for building a new component that interfaces with an external web service. To get started, first launch the Sharendipity editor.
Create new object type
Creating a new type provides you with the ability to define custom assets that perform a particular job or store specific data. They don’t necessarily have to be a displayable actor inside your World. The definitions for these new assets are entirely up to you.
In the case of a web service, you’ll define the location of the service, describe inputs, and then define custom actions that let the users of your service interact with it.
- Open the Explorer dialog and select New from the Types tab.
- Name your new type. For example, “Twitter Service – public timeline”
- Declare that your new type “is a REST Web Service” by clicking the + sign next to its name, and selecting the is a button. You can find the REST Web Service type by selecting Other… and navigating to the Local->Types tab in the Explorer that is launched. The following diagram highlights this navigation.
Default properties
Once you have the REST Web Service type defined, you must specify the details of your web service by initializing a couple of parameters.
Custom properties
Many web services have optional and required parameters. For instance, the Posterous API lets you specify the subdomain of the site you are reading from. In order to define parameters, you must define custom properties in your type that are of type REST Input.
Each REST Input has a name and value pair. The name value should be the parameter name as defined by the web service API you are trying to access. In the Posterous example, the name field is ‘hostname’. The value field carries your parameter value. When the web service is invoked, each REST Input is automatically appended to the end of the URL property.
If you were to look at the full URL when the service is invoked, you’d see something like the following:
http://posterous.com/api/readposts?hostname=gregtracy
As you are making calls to the web service, you can simply manipulate the value parameter of the REST Input to change your query to the respective web service.
Web service actions
By default, there is a single method defined for all web service types called invoke web service. This is the mechanism by which you initiate a call to your web service. It can be called internally as well as externally by users of your component.
Just like other objects in the system, you can create your own behaviors, methods, and properties for your new type. For instance, you may want to create your own invoke method which takes parameters that are passed to the web service. For example, passing in a user ID to a Facebook web service to specify the user whose profile you would like to access.
Referencing the service
Once you’ve defined your web service type, you can share it with the rest of the community with the Save option found in the object builder. Otherwise, the web service will be saved along with the application you’ve defined it in.
Whether or not you share it, the new type can now be accessed from anywhere else in the application.
- If you drag it into your World and drop it, you will be prompted to create a new custom property for the World.
- You can drag it into a behavior or method and drop it to create a local variable inside your logic.
- It will also be accessible from the Other tab when you define new properties anywhere within your application.
Just remember that if you don’t save the service by itself, you can only access is from the Local tab of the Explorer within the current application. If you do save it, it will appear in the Types tab for everyone.
Tips for better reuse
Creating an abstraction of the web services call is a nice feature by itself. However, it becomes most useful when you provide really easy access to the data that is returned. For instance, rather than simply providing the invoke web service call and letting the callers parse the data returned, try creating methods that do that parsing for them.
- The Twitter service has a method that returns an array of Twitter Status types.
- The Posterous service has a method that returns an array of Posterous Blog Post types.
- The Facebook User service has a method that returns an array of Facebook User types.
Each of these services define new methods that call the invoke web service method internally and parse the return data automatically. This way, users of the services don’t have to worry about how any of the data is formatted.
For more details, including specifics for the Facebook integration, check out the web services page on the wiki.
Tags:
create,
howto,
invoke,
web services
•
We’ve talked in the past about a creative, non-gaming example that visualized Google spreadsheet data. Since that post, we’ve had a few people inquire about some of the details behind that application. There’s a strong desire to visualize spreadsheet data, and this post outlines not only the Sharendipity components used, but also some of the hidden features of Google Docs that make the web services possible.
Web Service Components
The featured example uses a shared component type, “Google spreadsheet reader”. Internally, this component uses “Google Service – cell spreadsheet reader” to interface with a specific Google Doc. Both components are configured with a URL describing where the spreadsheet has been published. Note that this URL is not the URL you would see in your browser. Rather, it is a specific URL describing the published version. The steps for acquiring the publishing URL are below.
Google spreadsheet reader
This spreadsheet reader was designed specifically for visualizing a two-column layout. It assumes that the first column contains labels and the second column contains values. It is intended to be a convenience interface for these types of data layouts. If you’d like to access arbitrary data layouts, I recommend building new logic around the generic cell spreadsheet reader defined below.
Methods:
- getValue(String label) – Returns the value that corresponds to a specified label.
- getRowTuple(int index) – Returns a string for the specified index into the values. The string returned is of the form “label,value”.
- getValueMap() – Returns the hash map of all the data in the spreadsheet. It is a map of Strings and is keyed by the spreadsheet labels.
Google Service – cell spreadsheet reader
This web service is a raw conduit to your Google spreadsheet. It is the underlying web service used in the above reader as well. It assumes nothing about the layout of your data and provides a single method to access a specific cell. This reader uses a brute force technique for finding data so it is recommended that you cache the values once you’ve extracted them.
Methods:
- getCell(String cellID) – Returns the value for a specified cell. An example cellID would be “A3″ or “D104″, etc.
Accessing Google Doc Feeds
In order to access your Google spreadsheet through these components (or other Sharendipity web services) you must first publish the document. The components described in this post assume the data is published in a particular format as well. The following steps outline how to do this within Google Docs.
- Open up your spreadsheet from Google Docs
- Publish it using the blue “Share” button in the upper right hand corner of the document window. When the publishing dialog appears, click the “Start publishing” button to begin the publishing process.
- Next, change the link type from “Web Page” to “ATOM”
- Change the link type from “List” to “Cells”
The web service URL will be printed in the preview box. This is the URL that you will feed into the Google spreadsheet reader component using the URL property.
Consuming Google Components
The two existing Google components have customization points that make them easy to reuse. Each time you drag one of them out of the Explorer and into your application, you will be prompted to enter information for your spreadsheet, including the URL you configured in the previous section. The one caveat to this is if you define a variable inside a method or behavior that is of one of these types (rather than explicitly dragging it into your application). In that case, you must initialize the properties programmatically.
- The Google spreadsheet reader has the following configuration screen, and assumes a strict layout inside the spreadsheet. The screen has the same general form as other integration steps and was defined by the author of the component.
- The Google Service – cell spreadsheet reader has just one configuration step – describing the URL for your published spreadsheet feed.
These aren’t the only elements in the Food Drive application. However, they are the foundation. Once you have access to the data, it’s just a matter of using it to scale the objects you are using in the graph. In the Food Drive case, the bar graphs were created and their size was calibrated according to the appropriate value in the spreadsheet.
Now you’re ready to start visualizing your Google spreadsheet data! These components don’t meet your needs? You’d like to access the data in a different format? No problem… you can always create your own web service. We”ll follow up later with a post that describes this process in more detail.
Tags:
google,
google docs,
web services