::Developers » Services » Interface

Services

The interface to a service.

A service is located at a URL (eg. http://services.example.com/demo). The trailing slash should not be included. The following resources are expected to be served from the service:

The homepage

GET /

A welcome page. This page should state the name of the service and what it does. It should provide users with all they need to know about the service. It can also users to go to Sosius and add it as one of the user's services. This can be done via a special link: http://my.sosius.com/services/[handle]/add?redirect=http%3A%2F%2Fservices.example.com%2Fdemo%2F

The "action"

A service can be written to be used on item (node) pages and/or profiles (member). If the service is intended for a node it should expect a nodeID in the params. Alternatively if it is for a profile it shoudle xpect a member param. Examples of both are displayed below.

GET /
?do=action
&user=[username]
&nodeID=[nodeid]
&key=[md5 hash of [user]-[nodeID]-[consumerSecret]]

GET /
?do=action
&user=[username]
&member=[username]
&key=[md5 hash of [user]-[member]-[consumerSecret]]

Parameters

do
Has a value of "action".
user
The user who initiated the service. This is specified as a username rather than an id because members are referenced in the API via their username: /members/[username]
member
The username of the member whose profile the service was initiated from. Once again, the username makes it easy to look up the member in the API.
member
The username of the member whose profile the service was initiated from. Once again, the username makes it easy to look up the member in the API.
key
The key is intended as a way to ensure that that user and nodeID/member in the querystring are legitimate and have not been hacked by a user who is entering data directly into the URL. It is recommended that each service check the user and nodeID/member against the key each time.

Other requests

The service script can of course handle other requests in certain circumstances, however, the above specifies the bare minum of what needs to be supported. The Demo Service, for example, has a "do=authorize" section which handles a user coming back from being authorized using the OAuth callback.

Advanced features

Services do also a couple of advanced integration options which can be implemented by a Sosius administrator for certain trusted services.

It is possible to have a do=create interface params with accompanying create config options. This allows for the display of an Icon and description during the creation of an item. For example, a user clicks "Create", "File" and then might see "Demo file". Clicking this option would launch a window allowing the creation of a file. It is envisaged that only a limited number of Services will require this feature. If you believe you service needs access to this functionality please contact us.

Trusted Services also have the option of the automatic creation of an Access Token. This avoids the authorization step which needs to be carried out by the user. Only services with a proven track record and audited code will be allowed this option. If you believe you service needs access to this functionality please contact us.