OpenSocial .NET Client Library
==============================

http://code.google.com/p/opensocial-net-client/


Table of Contents
-----------------
1. Introduction
2. Package Contents
3. How to use
4. Limitations


1. Introduction
---------------
This library allows you to communicate with the RESTful services of OpenSocial container servers.
It is a .NET 3.5 library (written in C#) based on the OpenSocial Java Client Library and it is licensed under the Apache License 2.0.
For more details, read:
http://sites.google.com/site/opensocialdraft/Home/restful-protocol-specification


2. Package Contents
-------------------
The source code contains:
- /src/OpenSocial.Client: The library providing the data and API to consume the RESTful services.
- /src/OpenSocial.Tests: Contains NUnit tests and some classes illustrating how to use the library.
- /src/OpenSocial.Sample.Web: An ASP.NET project illustrating how to use the library in this context.
The library depends on a few open source libraries; read NOTICE for more details.
A modified version of OAuth.Net is included; its references to the Castle libraries were removed.


3. How to use
-------------
- First, open /src/OpenSocial.sln using Visual Studio 2008.

- Gadget.xml:
Before you can run any REST request (using your own ID), you need to install a gadget. You can install one of these:
+ http://opensocial-net-client.googlecode.com/svn/trunk/src/OpenSocial.Sample.Web/gadget.xml
+ http://opensocial-resources.googlecode.com/svn/samples/rest_rpc/sample.xml

- OpenSocial.Tests:
This project works as a repository of NUnit test cases and it also work as a command line program executing simple requests (Check the Display* classes).
For example, the class DisplayMore retrieves the friends of the viewer and all their albums/photos. By default, it uses an existing account, so it should work without any modification.

- OpenSocial.Sample.Web:
If you are planning to build an ASP.NET website, this project provides the basics of how to use the library to make OpenSocial requests.
There are a few steps to follow to set it up:
a. Upload gadget.xml (along with the whole project, if you want), verify that you own it (https://www.google.com/gadgets/directory/verify) and add your consumer details to the list of knownGadgets in the method Default.Page_Load().
This is optional, you can just use this one: http://opensocial-net-client.googlecode.com/svn/trunk/src/OpenSocial.Sample.Web/gadget.xml
b. Install the gadget. For Orkut, the page to use is: http://sandbox.orkut.com/Main#MyApps.aspx
c. Publish the ASP.NET project online
d. Load the application, paste url of the published ASP.NET website and press "Load".
e. You should see a TextBox containing the trace of all the requests made.

Note about the authentication process: There are many steps that are executed before you can make any requests.
a. The gadget initiates a signed request to the provided url (done in gadget.xml).
b. The website (Default.aspx) receives the request, verifies it and records the viewer's details.
c. Default.aspx returns some HTML requesting the gadget to reload it inside an iframe (this is required to load its AJAX scripts, etc.)
d. Default.aspx retrieves the OpenSocialClient and keeps it in its session state
e. Whenever you make a request (like "Show Friends"), the server uses the OpenSocialClient to do it.
More details here: http://sites.google.com/site/oauthgoog/2leggedoauth/2opensocialrestapi


4. Limitations
--------------
- /src/OpenSocial.Client/Client/OpenSocialRequestValidator is used to validate the signed request made by the container. This is important for security reasons. At the moment, its implementation is faulty. So the ASP.NET project contains hacks to accept a request even if its validation fails.
- This library does not implement most of the services specified in OpenSocial 0.9. Check /src/OpenSocial.Client/Client/OpenSocialClient to see what is supported.
- The overall architecture also needs some refactoring to better accommodate all the services and features.