::Developers » Services » Getting Started

Services

A guide to getting started with Services in Sosius.

Overview

This document provides an overview of how to set up a service and get it integrated into Sosius. It will use the Demo Service to show how this is done. Currently we have not any real life implementations of the Demo Service, however, they soon will be added to the site. For now, we will work along with a pseudo code version which should be easy for you to adapt to your language of choice.

Publish Service

Once you have coded your Service, or at least a basic version of it, you should publish on the web somewhere which is publicly accessible. The Demo assumes that the code is located at http://services.example.com/demo/. Once the code is up and running on the web we can look to integrating it into Sosius.

OAuth

Probably the trickiest aspect of the system is coming to grips with OAuth. We recommend that you read the OAuth spec and understand (i) the main players: user, consumer, application and (ii) the four stage process: request token, authorization, access token, api request. You then just need to grab an OAuth client in your favourite language to ease the process.

Register Service

The next stage is to tell Sosius about your new creation by registering the Service with us. There are quite a few configuration options to consider here.

Make sure that you are logged in and the go to My Account. If you look down to the bottom left of the page you will see a link to Developer Services. This page will list out any services you have added and allows you to create a new service. Click the create button to start the process.

At this stage we check to make sure that you have at least one Consumer created. A Consumer is created in order to deply a Service because the Consumer secret is required to understand the "key" sent to the Service. It is also used in making requests to the API via OAuth. If you have not yet created a Consumer then you are requested to make one. Otherwise you can select from a list of any consumers you have made already. You can always manage your Consumers at Developer Consumers.

OK. You have a consumer set up. Now it is time to fill in the form. Here is a run down of the various fields.

Title
The title of the service. This should accurately describe what your service is about. This is the title the service is know as on the /services page. Set this to "My Demo" or similar.
Handle
Each service has a unique handle. This is used on the service homepage: /services/[handle]. Set this to something like "myusername-demo"
Description
A short description of the service displayed on the service homepage.
URL
The publicly accessible URL for the service. Include the http:// and do not include the last slash. Set this value to whereever you published your service: "http://services/example.com/demo".
Consumer
Every service needs a consumer. Select from one of the consumers you have previously made. Read more about the OAuth spec to understand about the role a consumer plays in the OAuth process.
For Items
Services can apply to Items (nodes). Check this box if the service is intended to work with items. The Demo service is meant to work with items so check this box.
For Profiles
Services can apply to Profiles (members). Check this box if the service is intended to work with profiles. Leave this unchecked for the demo.
Is Private
users can only subscribe to public services. You should set this to Private during the testing phases of the service.
Action Title
The title of the button which launches the service. Set this to "Demo!"
Action Description
The helper text on the button which launches the service. Set this to "See my demo".
Action Item Types
The item types which the service will apply to (if it applies to items at all). You must specify the items here. If none are checked then the button will not show. For the demo try setting it for Folder.
Action Extensions
It is possible to specify a comma seperated list of file extensions to which the service will apply. eg. doc,ppt,xls. This is an advanced feature but is helpful to distinguish certain kinds of files. Make sure you have File and/or File Version checked if you specify anything here. You can leave this blank for the demo.
Action Sub Type
Items can have a "sub type pis" applyed to them in certain cases. At the moment this is only done via special applications (photo book) and entries in tables. ie. Currently it is not a widely dispersed feature. However, it is possible to apply a Service to items of a certain sub type if it has been specified. You can leave this blank for the demo.

Service Thumbnail

Once you have created the sevrice you should upload a thumbnail. The thumbnail image will be displayed on the service's page as well as on the action button. It is therefore an important part of your service's branding. If you do not upload a thumbnail a generic icon will be shown.

We recommed uploading a 32x32 px gif or png image. This larger version will be shown in the service's page. A 16x16 thumbnail will be made for the action page.

Review Service

Congratulations, you have now completed the integration of your Service with Sosius. Now, lets review what it looks like and start to test it.

At this stage the Service will have a rating of 0 and the service will not be listed at /services, even if you have the Is Private flag set to off. If you would like to have a service rated and listed then please contact us. In order for the service to appear in the Services list which appears for all users it must be given a rating of at least 2 by Sosius. You can request a rating at any time. If the service is not deemed suitable for ordinary use it will be given a rating of 1.

However, you can still access your service at /services/[handle]. This is the home for your service on the system and you should publicize this URL to encourage users to start using your Service. Go the the service Homepage and click "Add Service". The service should now be working for you. Navigate to any folder and you should see a button in the toolbar for your demo: "Demo!". Click it and see what happens.

If the demo is operating properly you will be sent through to the service (?do=action). The Demo service will then send you to bach to the Sosius authorize page so that you (the user) can authorize the Consumer to use the app. At this stage you will probably be logged in so authorization will just be a matter of clicking a single button. If you have been logged out due to inactivity you will be asked to log in again. You will then be returned to the service. If all goes well the contents of the node (XHTML version) from the API will be echoed back to the screen.

We'd love to hear about any Services you create. Let us know.