Introducing MashPoint REST API for SharePoint

In November, Bamboo released version 1.0 of MashPoint.  As you know, MashPoint enables integration of  your line of business (LOB) applications in SharePoint using the same architecture as the MOSS BDC.  Now you can easily make this data available in SharePoint, but this is only half the story.  What about the "Mash" in MashPoint?  How will MashPoint enable real enterprise mashups?  The short answer is by leveraging Bamboo Web Parts to display and combine your data.   We are steadily updating our Web Parts to be able to consume MashPoint data as well as SharePoint data.  If you are comfortable writing your own Web Parts, we also encourage you to use the MashPoint platform to access your external data.

So the story for the "server side" is pretty solid, the BDC APIs are server side APIs.  But what if you want to access this data "client side," be it in an AJAX application running in the browser, from a .NET application running on your workstation, or in Microsoft Office? To support these scenarios, we are now releasing a preview of our REST API for MashPoint and SharePoint.

This will allow you to create client side "gadgets" that require no assemblies on the server and still have access to the entire SharePoint object model as well as your LOB systems through the REST API.  These scenarios will be more and more popular as we move to hosted solutions and cloud-based computing.  The API supports multiple standard representations; out of the box we support XHTML, ATOM+XML (Both ADO.NET Data Services and GData) and JSON.  For specific resources we also include support for vCard and iCalendar. The MashPoint REST stack is fully extensible so you can add your own serializers and mappers (I'll describe this in a later post) and you can expect Bamboo and our partners to release more add-ons in the future.

So by installing our REST API, you will make SharePoint "mashable."  No more Web service calls into lists.asmx or sitedata.asmx, where one service returns XML data and the other one strongly typed objects.  You don't have to write your own Web service endpoint and deploy it if all you want is access to SharePoint data.  You can get to anything through the REST API in a uniform way. Everything is now addressable, even Web Parts on a page.  Imagine having Web Part connections across the Internet.

Install MashPoint REST

Enough "talking," let's take a look at how this works by exposing the AdventureWorks database in a RESTful way through MashPoint. This assumes that you already have MashPoint installed or that you are running MOSS Enterprise edition with our MashPoint runtime components installed. 

First we need to download the installer.  Extract the zip file to a folder on your SharePoint Web front end server, start Setup.bat, then click install.

 install.screen

 

Next you will have to select the WebApplications where you want the REST API installed. Here we select Central Admin, our BSSP and the "default SharePoint Web site." You can also select "Automatically activate features" so you don't have to manually activate the features.

install.webapps 

Accessing MashPoint REST

When the setup has completed, browse to your default Bamboo Shared Service provider site or, if you are running MOSS Enterprise with the MashPoint runtime components, go to your SSP site.

default.html

 

Now let's address into MashPoint - by adding mashpoint/1/ to the URL, my URL becomes:

http://jonasvista:27250/mashpoint/1/bssp/admin/default.aspx.

This should give you a page looking something like this.

default.aspx

 

For all you developers out there, it should look somewhat familiar. Let's take a look at the page source. Either use View source or bring up your favorite XML editor and open the page like this.

view.source

 

What's nice here is that Visual Studio can consume our REST services, and so can Notepad. Soon even your refrigerator will be able to issue an HTTP GET.  ;)

Below is a snippet of what you will see. It's XHTML describing the SPFile instance.  You get the XHTML representation unless you specify a specific one using the Accept-Types or by using uri tokens. This is  a very important part of the protocol since it allows you to discover the object model by just using your Web browser. Since it's XML, it's also a perfectly valid format to use for your clients if you don't want to get the data in ATOM+XML or JSON format.

Let's look at the format a little bit closer. Our goal is to use semantic markup so that the markup returned describes the object and has nothing to do with the display of the data. We do add a small inline style-sheet that is used to generate a nicer visual experience. We use the class attribute to indicate what type it is and we use anchor elements to link to related objects and collections. The anchor always has a rel attribute indicating what resource the link is referring to. So it's a complete markup that can be used by your client side applications. And I'm pretty confident that you will enjoy the fact that it is discoverable by just using your favorite Web browser.

xhtml 
 

To select a different representation of the resource, you can use special tokens in the URL. This is to support switching representations when you can't control what Accept-types are being sent. Try to get the resources as application/atom+xml by adding the $atom$ token and use $json$ to get the resource in application/json format.

http://jonasvista:27250/mashpoint/1/$atom$/bssp/admin/default.aspx

http://jonasvista:27250/mashpoint/1/$json$/bssp/admin/default.aspx

json

 

atom

 

Now let's browse to MashPoint by changing the URL to the root Web http://jonasvista:27250/mashpoint/1/bssp/admin/. Since this is the host for the Bamboo Shared Service, and thus it's always associated with this BSSP, you will see the $MashPoint$ link. Select this link to get into MashPoint.  Notes: You must have MashPoint installed on your system in order to try the following steps.  Read more about MashPoint and download here.

mashpoint.link

mashpoint.root

 

You are now at the root of MashPoint. From here you can go into Administration, Model or the Runtime part. If you are familiar with MashPoint and the MOSS BDC you know that you use the Administration objects to edit the Application definitions and create new ones, and the model gives you runtime information about the meta data of the applications. Before we go further into this, let's switch views and look at the application definitions we have uploaded into MashPoint by switching to our well known HTML representation. Let's change the URL back to http://jonasvista:27250/bssp/admin/default.aspx 

default

 

Select View Applications. This should give us the view of installed applications.

mashpoint.applications

 

Here we can see that I have the AdventureWorksSample installed along with the Amazon Web Service sample and a connection to the Bamboo Solutions CRM system. Now we will switch back to the MashPoint view to see how we can access this information.

We have put a lot of work into getting uri "fidelity" so you can easily switch between the SharePoint URL and the MashPoint object model representation simply by adding mashpoint/1/ after your server name, but it does not work when you are in _layouts.

So type in your equivalent of http://jonasvista:27250/mashpoint/1/bssp/admin/$MashPoint$ then browse to Admin > LobSystems and you should see the list of LobSystems. The URI is pretty self explanatory telling us what we are looking at http://jonasvista:27250/mashpoint/1/bssp/admin/$MashPoint$/Admin/LobSystems

mashpoint.lobsystems

 

And next browse into the AdventureWorksSample LOB system.

mashpoint.adventureworks 

Making the application definition accessible using the REST api.

We need to add some special properties to tell the REST runtime what HttpVerbs to associate with the different method instances. If all you want is a read only view you don't need to do this, but we map the finder method instance to the GET verb and the specific finder to GET with a unique key. If you want a complete CRUD experience, you do need to decorate your Delete method with the Http DELETE verb and your Update method with Http PUT and your create method instance with HTTP POST.

<MethodInstance 
    Name="ProductFinderInstance" 
    Type="Finder" 
    ReturnParameterName="Products">
  <Properties>
    <Property Name="HttpVerb" Type="System.String">GET</Property>
  </Properties>
</MethodInstance>
<MethodInstance 
    Name="ProductSpecificFinderInstance" 
    Type="SpecificFinder" 
    ReturnParameterName="Products">
  <Properties>
    <Property Name="HttpVerb" Type="System.String">GET</Property>
  </Properties>
</MethodInstance>

As you can see, in the above example we have two method instances decorated with HTTP GET, the runtime picks the instance that most closely matches the URL parameters.

Let's access the Products using HTTP.

The URL has the following format: {site}/$MashPoint$/Runtime/{LobSystemInstance}/{Entity}. Because of this, I encourage you to name your entities in a plural form since it's a collection.

http://server/$MashPoint$/Runtime/AdventureWorksSample/Product

products

 

This executes the Finder with the default parameters defined in the Application definition. Now let's apply a filter so we need to see what filters are specified. To showcase the "discoverability" of the API, we will do this by switching to the Model by replacing Runtime with Model in the URL.

model

 

Then select the FinderMethodInstance > Method > InputParameters and you will see what parameters are defined. Now let's filter out all products starting with the letter A.

filter 

We add the parameter @Name to the URL that we had before so the should look like this:

http://jonasvista/mashpoint/1/$MashPoint$/Runtime/AdventureWorksSampleInstance/Product?@Name=A%

 

product.search

 You now have all products starting with the letter A.

Summary

This should give you an idea of what is possible with MashPoint. In the coming weeks we will post more articles describing how you can access the SharePoint object model using MashPoint REST, how security works, and  we will also show you how to write extensions to the API.

• Download MashPoint REST API
• Discuss MashPoint REST API
• Extend SharePoint to the cloud with MashPoint REST API
• Read additional MashPoint articles

 


Posted Dec 17 2008, 01:08 PM by Jonas Nilsson
Filed under: , ,

Blogs

    MashPoint - A Breakthrough in SharePoint Data Integration
  • Home

Jonas Nilsson Q&A

Bamboo Nation Almost Everywhere

Bamboo Solutions on Facebook

Bamboo Solutions on Google+

Bamboo Solutions on LinkedIn

Bamboo Solutions on YouTube

Bamboo Solutions Corporation, 2002-2014