Open Collaboration Services v1.6

Changelog

Differences between 1.5 and 1.6 PERSON:

man -> male extended-attributes: add lastmodified
CONTENT:

voting. support for votes from 0 to 100 gpgfingerprint to content add,edit,download,get gpgsignature to content add,edit,download,get support packagenamer/repository in add,edit,download add a summary field add a feedbackurl list add support for search for distributions or licenses add support for icons to list and get support for video files support to fetch recommendations.
COMMENTS:

provider file - a xml configuration file which maps clients to service providers

Requirements

Performance / Scalability

the services should be usable by millions of people at the same time. because of that it is important to build the architecture in a scalable way. every component of the architecture must be cluster enabled. this means that it must be possible to implement every service or component in a server cluster.

Security

the data transfer should be encrypted if possible.

Privacy

it is essential to respect the privacy requirements of the people. every person must have full control over the personal information.

Vendor Independent

it is important for an application to be independent of a specific websites or services because of that we use independent provider files who map the clients to the service providers. For example the KDE project has provider files hosted on the KDE.org server who contains a list of providers who are providing a specific service. So the application maintainer has full control over which content and services are accessed by the application (client)

Architecture

REST

We use REST for the webservices calls. Unlike, for example SOAP, REST is very, lightweight, easy to learn and implement and cachable. REST is very widespread in the internet and is used by other popular webservices. REST support is integrated into various web or desktop frameworks and it is platform and technology independent The data exchange format is XML. If you add the format=json parameter you can also get the data in JSON format.

SSL

we suggest to use ssl to encrypt the data transfer between client and service providers. unencrypted data transfer is also possible when a SSL it too expensive or slow.

Authentication

most services require a authenticated user. this is important for legal reasons. and to prevent DOS attacks. At the moment we support autentification via login/password or an API key. You have to get the API key from the service provider We will support OpenID in a later version of the specification.

example login/password

example api key

Proxy

it is possible to implement proxy service provider to integrate other proprietary webservices.

Date Format

All date and time data is in ISO 8601 format.

Services

the applications or websites do not have to support every service. We suggest to implement only the services into the clients or service providers which are usefull for the users at this point.

At the moment there are the following services:

CONFIG

PERSON

FRIEND

MESSAGE

ACTIVITY

CONTENT

FAN

KNOWLEDGEBASE

EVENT

COMMENTS

PRIVATE DATA

FORUM

...more to come later

Error Reporting

every response xml contains a "status", "statuscode" and a "message" tag. the status tag has only two possible values. "ok" or "failed". If the status is "failed" you can get a human readable errortext from the "message" tag. Examples of errormessages are: "data is private" or "person not found". You get a machine readable status in the "statuscode" tag. Statuscode 100 means "request sucessful", 999 means "unknown request". All other codes are specific to the called method and described below.

Versioning

we support versioning of the service specifications. so if we break the api in an incompatible way we can use a new version number and still keep the old API for legacy applications(client) please note that the api is currently in draft state. so it will change in the future

Provider files

it is important to decouple the applications from the services. so we suggest to use provider files to control the mapping of applications to service providers. if an application wants to access a services it first gets the provider file to get the list of available providers. than it can access the different providers and merge the results. An example provider file:

PERSON

The PERSON service is handling the access to user data. you can search people and access personal data of other people of the person made the information public. The personids are stored and shown case sensitive. But if you want to reference a person the personid is case insensitive.

check

Check if the given login and password or the API key is valid. It returns the associated username.

add

Registers a new user account on the server. The users still have to approve the account by clicking on a link in a confirmation email to activate the account. Only alphanumeric characters are allowed and the password has to be 8 characters or longer.

Syntax: /v1/person/add

Method: POST

POST Arguments: login - The login or the API key

POST Arguments: password - The password

POST Arguments: firstname - The firstname of the user

POST Arguments: lastname - The lastname of the user

POST Arguments: email - the email address. the address must be valid, because the user gets a confirmation email to this address.

search

find a specific list of persons. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. It is not possible to get a list of more than 1000 people because of privacy issues.

Syntax: /v1/person/data

HTTP method: GET

url arguments: name - A part of the name or personid you want to search for.

url arguments: country - The country id of the country you want to search in.

url arguments: city - The name of the city as a string.

url arguments: description - A string you want to search for in the description and other fields of the person.

url arguments: pc - A string you want to search for in the pc/hardware field of the person.

url arguments: software - A string you want to search for in the software field of the person.

url arguments: longitude - The longitude of the position where you want to find people.

url arguments: latitude - The latitude of the position where you want to find people.

url arguments: distance - The maximum distance of the person to you longitude/latitude position. if you specify the latitude and longitude but no distance the resultset will be ordered by distance. The unit of the distance parameter is degrees.

url arguments: attributeapp - The applicationname or namespace of the attribute.

url arguments: attributekey - The key of the attribute.

url arguments: attributevalue - The value of the attribute.

url arguments: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ...

url arguments: pagesize - The amount of entries your get per page.

Statuscodes:

100 - successfull

102 - more than 1000 people found. it is not allowed to fetch such a big resultset. please specify more search conditions

200 - too many API requests in the last 15 minutes from your IP address. please try again later.

ok100Frank1visible only for registered usersFrankTestmaledeveloperopenDesktop.orgwww.facebook.com/fooFacebookhttp://openDesktop.org/img/socialicons/emblem-facebook.pngopendesktop.orghttp://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg1http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg11973-07-25workingStuttgartGermanykarlikde-dev, plasmairc://irc.freenode.org/kde-devirc://irc.freenode.org/plasmalot of stuffnothingtravelenglishphp, c++ninfightclubut3http://www.KDE-Look.org/usermanager/search.php?username=Frank

get self

get the data from yourself. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

ok100Frank1visible only for registered usersFrankTestmaledeveloperopendesktop.orgopendesktop.orghttp://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg1http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg11973-07-25workingStuttgartGermanykarlikde-dev, plasmairc://irc.freenode.org/kde-devirc://irc.freenode.org/plasmalot of stuffnothingtravelenglishphp, c++ninfightclubut3http://www.KDE-Look.org/usermanager/search.php?username=Frank

edit

Update the latitude, longitude, city and country of myself. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

balance

get attributes

Gets the list of extended attributes of a person. You can store several attributes to you person record which are publicly readable for everybody. The attributes are key/value pairs with an "app" parameter as namespace. Store data which is only interesting for your application with your application name as a app namespace. If the data is of general interest use "global" as app parameter. The parameter "app" and "key" are optional in the url. So you access all the attributes from the person or only the attributes from a specific application or the only the value of one specific key. You can search for users which have specific attributes with the search method. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

syntax: /v1/person/attributes/"personid"/"app"/"key"

HTTP method: GET

Arguments: personid - The person from which you want to get the attributes.

Arguments: app - The application from which you want to get the attributes. This parameter is optional.

Arguments: key - The key of the attribute you want to get. This parameter is optional.

FRIEND

The FRIEND service is for handling friendship relations between people. you can get the friends of a specific person or from yourself. You can invite other persons as a friend and manage the invitations.

get

Gets the list of friends from a person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

syntax: /v1/friend/data/"personid"

HTTP method: GET

Arguments: personid - The person from which you want to get the friendslist.

URL Arguments: page - The page of the friendslist. The size of a page is controlled by the pagesize argument. The first page is 0, the second is 1, ...

MESSAGE

The MESSAGE services can be used to send and receive messages. this is always possible even if you don't know the real email address of the other person. The messages are stored in different folders. if you want to access a special folder like for example the inbox you should search in the folders list for a folder with the type "inbox" to get the right folder id.

folders

Gets a list of the availabe message folders. You need the ids if you want to access the folders via messagelist. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

list

Gets the list of messages from a specific folder. the messages are sorted in chronological order. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/message/"folder"

HTTP method: GET

Arguments: folder - The ID of the folder you want to get. Use the folders method to get the list of folders.

get

Get a message. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. the message will be marked as "read" if you access it with this method.

Syntax: /v1/message/"folderid"/"messageid"

HTTP method: GET

Arguments: folderid - The ID of the folder. Use the folders method to get the list of folders.

Send a message to "frank" with the subject "hello" and a messagebody "coding is fun"
Example:

ok

ACTIVITY

You can use the ACTIVITY services to see what is going on in your friends network. For example who visited you homepage, wo has send you a message and who uploaded a new content to the website. You can also post a microblogging message which is vivible on you profile page and in the activities of your friends. The entries are sorted by timestamp.

get

Gets the list of activities. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/activity

HTTP method: GET

URL Arguments: page - The activities page. The amount of entris per page is controlled by the pagesize argument. The first page is 0, the second is 1, ...

ok1002101not answered12345Applicationtesty2009-02-07T23:14:11+01:00app questionHow can I ........testy20http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12345>
2answered12345othertesty2009-02-03T21:11:01+01:00app question 22How can I 22........testy20http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12

get

Read one specific knowledgebase entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

ok1006bbbhere is the description textParty1970-01-01T00:00:00+01:001970-01-01T00:00:00+01:00FrankGermany002009-05-18T18:49:15+02:0012http://www.opendesktop.org/events/?id=6http://www.opendesktop.org/CONTENT/event-badge/0/6.png

add

Add a new event entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

PRIVATE DATA

get attributes

Gets the list of my personal extended attributes. You can store several attributes which are only readable to me. The attributes are key/value pairs with an "app" parameter as namespace. Store data which is only interesting for your application with your application name as a app namespace. If the data is of general interest use "global" as app parameter. The parameter "app" and "key" are optional in the url. So you access all the attributes from yourself or only the attributes from a specific application or the only the value of one specific key. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

syntax: /v1/privatedata/getattribute/"app"/"key"

HTTP method: GET

Arguments: app - The application from which you want to get the attributes. This parameter is optional.

Arguments: key - The key of the attribute you want to get. This parameter is optional.

BUILDSERVICE

The build service module handles a user's access to build services, used to create distribution packages for the platforms supported by those services, and afterwards distribute to distribution sites which support the package formats produced by these various services.

Projects

create

Create a new project for the authorized user, optionally inserting information into the project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

uploadsource

Upload a new source bundle (a compressed file in .zip, .tar.gz or .tar.bz2 format) containing the source code of the project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Note: If the project has not had a source file uploaded yet, and the specfile data field for the project is empty (that is, nothing has been entered manually), this will also fill that field with an automatically generated spec file.

Syntax: /v1/buildservice/project/uploadsource/"project"

HTTP method: POST

URL argument: project - projectid, the id of the project to generate a spec file for

Remote Accounts

list

Get a list of all the remote accounts a user has added references to. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/remoteaccounts/list

HTTP method: GET

Result: remoteaccountslist xml
* id - remoteaccountid (int), the ID of the remote account entry
* type - int, which type of account we're dealing with (1 is buildservice, 2 is publisher)
* typeid - string, the ID of the remote service the account is with
* data - string, any arbitrary data you wish to associate with the account
* login - string, the user's login on the remote service
* password - string, the user's password on the remote service

edit

Change the details of a specified remote account for the authenticated user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/remoteaccounts/edit/remoteaccountid

HTTP method: POST

URL argument: remoteaccountid - the ID of the remote account you wish to change details for

POST argument: data - string, any arbitrary data you wish to associate with the account

POST argument: login - string, the user's login on the remote service

POST argument: password - string, the user's password on the remote service

get

Get the details of a specific remote account. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/remoteaccounts/get/remoteaccountid

HTTP method: GET

Result: remoteaccount xml
* id - remoteaccountid (int), the ID of the remote account entry
* type - int, which type of account we're dealing with (1 is buildservice, 2 is publisher)
* typeid - string, the ID of the remote service the account is with
* data - string, any arbitrary data you wish to associate with the account
* login - string, the user's login on the remote service
* password - string, the user's password on the remote service

remove

Remove the specific remote account from the user's list of remote accounts. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Build Services

list

Get a list of all the build services available. If the user is not authenticated the complete list of services is returned. If the user is authenticated the list is returned of build services that user is signed up for. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/buildservices/list

HTTP method: GET

URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ...

URL argument: pagesize - The amount of entries your get per page.

Mandatory fields: none

Result: buildservicelist xml
* id - int, alias of buildserviceid, the build service's ID
* name - string, human readable name of build service
* registrationurl - url, link to the service's registration page
* supportedtargets - list of targets, made up of an integer id and a string name

Result: buildservice xml
* id - int, alias of buildserviceid, the build service's ID
* name - string, human readable name of build service
* registrationurl - url, link to the service's registration page
* supportedtargets - list of targets, made up of an integer id and a string name

Build Jobs

list

List the jobs a user has, optionally for a single project. If projectid is specified, only build jobs for that project are retruned. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/jobs/list/"project"

HTTP method: GET

URL argument: project - projectid, the id of the project to list build jobs for

URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ...

get

Get information about a build job. See also getoutput. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/jobs/get/"buildjob"

HTTP method: GET

URL argument: buildjob - buildjobid, the id of the build job you wish to retrieve information about

Mandatory fields: "buildjob"

Result: buildjob xml
* name - string, a human-readable name for the build job
* status describes the current state of the build job, and is an enumeration over the following values
* 1 - Running
* 2 - Completed
* 3 - Failed
* progress - float, 0 to 1. If progress is unknown, 0 is passed
* url - url, link to the page on the build service which shows this particular job's status
* message - string, any message the build service might have

getoutput

Get the build output from a specific build job. This is the clear text version of the configuration, compilation and other steps. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/jobs/getoutput/"buildjob"

HTTP method: GET

URL argument: buildjob - buildjobid, the id of the build job you wish to retrieve the output for

Mandatory fields: "buildjob"

Result: output - string, the output of the build service - full output, as in compiler output etc.

Publishing

getpublishingcapabilities

List all the available publishers. In the case of an authenticated user, the function will return only the publishers that the user has an account with. Authentication is done by sending a Basic HTTP Authorisation header.

Status 102 is informational and in essence is a success. It is meant as a convenient way of finding out whether to bother parsing the list of publishers.

Syntax: /v1/buildservice/publishing/getpublishingcapabilities

HTTP method: GET

URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ...

URL argument: pagesize - The amount of entries your get per page.

Result:
* publisheridlist - a list of publishers, see buildservice/publishing/getpublisher

getpublisher

URL argument: publisher - publisherid, the id of the publisher about whom to retrieve

Mandatory fields: "publisher"

Result: publisher xml
* name - string, the human-readable name of the field, also used as identifier
* registrationurl - url, an address to give to the user to allow for easy registration
* fields - a list of the supported fields
* id - publisherid, the publisher's ID
* name - string, human readable name
* fieldtype - type name, value from the following itemized list:
* string
* longtext - used for longer descriptions and the like
* integer
* float
* item - an item from the provided list of options
* boolean
* datetime
* url
* image
* options - a list of options. If this is populated on string type, use a combo box to provide the user with suggestions, but accept any string. If two items are present for integer and float values, they represent the lower and upper limits of the values respectively. In the case of a field of type image, the items will be, in order, maximum width and height in pixels, and maximum filesize in bytes.
* fieldsize - int, maximum number of bytes allowed, when applicable (this is 0 if not used)
* required - boolean, whether or not the publisher requires this field
* supportedtargets - list of targets, same naming as in jobs/getbuildcapabilities

savefields

TODO: This needs a publishing site association as well, otherwise we can't check the field type properly...

Save field data relating to a particular project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/publishing/savefields/"project"

HTTP method: POST

URL argument: project - projectid, the id of the project to save field data for

POST argument: fields - a list of field data:
* name - string, the name of the field (same identifier as publishing/getpublisher)
* fieldtype - string, the name of the data type, see list in publishing/getpublisher. This allows for two same-named fields to have different data if their field types are different. If the type is
* data - data according to fieldtype

getfields

Get the field data from the previous publishing of a particular project. In the case of a project with no field data saved, an empty list will be returned. This should be interpreted as a success, as only saved data is returned, and data for any aditional fields is not included as empty, since the knowledge of which fields are required now is not available. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Syntax: /v1/buildservice/publishing/getfields/"project"

HTTP method: GET

URL argument: project - projectid, the id of the project to fetch old field data for

Mandatory fields: "project"

Result: fields xml - a list of field data:
* name - string, the name of the field (same identifier as publishing/getpublisher)
* fieldtype - string, the name of the data type, see list in publishing/getpublisher. This allows for two same-named fields to have different data if their field types are different.
* data - data according to fieldtype