Specifications/open-collaboration-services

Open Collaboration Services (v1.4)

Frank Karlitschek MailTo(karlitschek AT kde.org)

Contents

  1. Open Collaboration Services (v1.4)
    1. Purpose
    2. Examples
    3. Naming
    4. Requirements
      1. Performance / Scalability
      2. Security
      3. Privacy
      4. Vendor Independent
    5. Architecture
      1. REST
      2. SSL
      3. Authentication
        1. example login/password
        2. example api key
      4. Proxy
      5. Date Format
      6. Services
      7. Error Reporting
      8. Versioning
      9. Provider files
    6. Service Specifications
      1. CONFIG
        1. config
      2. PERSON
        1. check
        2. add
        3. search
        4. get
        5. get self
        6. edit
        7. balance
        8. get attributes
        9. set attribute
        10. delete attribute
      3. FRIEND
        1. get
        2. receivedinvitations
        3. sentinvitations
        4. invite
        5. approve
        6. decline
        7. cancel
      4. MESSAGE
        1. folders
        2. list
        3. get
        4. send
      5. ACTIVITY
        1. get
        2. put
      6. CONTENT
        1. categories
        2. licenses
        3. distributions
        4. dependencies
        5. homepagetypes
        6. list
        7. get
        8. download
        9. vote
        10. add
        11. edit
        12. delete content entry
        13. upload new download file
        14. delete download file
        15. upload preview image
        16. delete preview image
      7. FAN
        1. get
        2. isfan
        3. add
        4. remove
      8. KNOWLEDGEBASE
        1. list
        2. get
      9. EVENT
        1. list
        2. get
        3. add
        4. edit
        5. delete event entry

Purpose

integration of web communities and web bases services into desktop and mobile applications. free, secure, privacy protected, vendor independent.

Examples

Naming

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

https://frank:password@api.opendesktop.org/v1/activity?page=3

example api key

https://API5142830791365744186814934@api.opendesktop.org/v1/activity?page=3

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:

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: 

<providers>

<provider>
 <id>opendesktop</id>
 <location>https://api.opendesktop.org/v1/</location>
 <name>openDesktop.org</name>
 <icon></icon>
 <termsofuse>https://opendesktop.org/terms/</termsofuse>
 <register>https://opendesktop.org/usermanager/new.php</register>
 <services>
   <person ocsversion="1.3" />
   <friend ocsversion="1.3" />
   <message ocsversion="1.3" />
   <activity ocsversion="1.3" />
   <content ocsversion="1.3" />
   <fan ocsversion="1.3" />
   <knowledgebase ocsversion="1.3" />
   <event ocsversion="1.3" />
 </services>
</provider>

<provider>
 <id>testy</id>
 <location>http://api.foo.org</location>
 <name>Foo provider</name>
 <icon></icon>
 <termsofuse>https://foo.org/terms/</termsofuse>
 <register>https://foo.org/register.php</register>
 <services>
   <person ocsversion="1.5" />
   <friend ocsversion="1.3" />
   <message ocsversion="1.3" />
   <knowledgebase ocsversion="1.2" />
   <event ocsversion="1.1" />
 </services>
</provider>

</providers>

The KDE provider file is here: http://download.kde.org/ocs/providers.xml

Service Specifications

CONFIG

config

get some basic API configuration information

Example: GET http://api.opendesktop.org/v1/config Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <version>1.4</version>
  <website>openDesktop.org</website>
  <host>api.openDesktop.org</host>
  <contact>frank@openDesktop.org</contact>
  <ssl>true</ssl>
 </data>
</ocs>

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.

Example: POST http://api.opendesktop.org/v1/person/check postdata: login="frank" password="123456" Checks if frank,123456 is a valid account. Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <person details="check">
   <personid>frank</personid>
  </person>
 </data>
</ocs>

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

Example: POST http://api.opendesktop.org/v1/person/add postdata: login="frank" password="123456" firstname="Frank" lastname="Karlitschek" email="karlitschek@kde.org" registers a new user account. Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

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.

Example: GET http://frank:password@api.opendesktop.org/v1/person/data?name=eter&city=don&description=development&latitude=11.2&longitude=22&distance=0.5&page=2&pagesize=10 Gets the third page of the search result list from the search for person where "eter" is in the nickname, firstname or lastname and "don" is in the city and who is interested in "development" and who lived near latitude:11.2 and longitude:22.0 witch a tolerance of 0.5

Example: <?xml version="1.0"?> 

<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <person details="summary">
   <personid>Testy</personid>
   <privacy>0</privacy>
   <privacytext>public</privacytext>
   <firstname>Peter</firstname>
   <lastname>-</lastname>
   <company></company>
   <gender></gender>
   <communityrole></communityrole>
   <city>London</city>
   <country></country>
  </person>
  <person details="summary">
   <personid>peter</personid>
   <privacy>0</privacy>
   <privacytext>public</privacytext>
   <firstname>Frank</firstname>
   <lastname>Test</lastname>
   <company>company</company>
   <gender>man</gender>
   <communityrole></communityrole>
   <city>London</city>
   <country></country>
  </person>
 </data>
</ocs>

get

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

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <person details="full">
   <personid>Frank</personid>
   <privacy>1</privacy>
   <privacytext>visible only for registered users</privacytext>
   <firstname>Frank</firstname>
   <lastname>Test</lastname>
   <gender>man</gender>
   <communityrole>developer</communityrole>
   <homepage>opendesktop.org</homepage>
   <company>opendesktop.org</company>
   <avatarpic>http://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg</avatarpic>
   <avatarpicfound>1</avatarpicfound>
   <bigavatarpic>http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg</bigavatarpic>
   <bigavatarpicfound>1</bigavatarpicfound>
   <birthday>1973-07-25</birthday>
   <jobstatus>working</jobstatus>
   <city>Stuttgart</city>
   <country>Germany</country>
   <latitude></latitude>
   <longitude></longitude>
   <ircnick>karli</ircnick>
   <ircchannels>kde-dev, plasma</ircchannels>
   <irclink>irc://irc.freenode.org/kde-dev</irclink>
   <irclink>irc://irc.freenode.org/plasma</irclink>
   <likes>lot of stuff</likes>
   <dontlikes>nothing</dontlikes>
   <interests>travel</interests>
   <languages>english</languages>
   <programminglanguages>php, c++</programminglanguages>
   <favouritequote></favouritequote>
   <favouritemusic>nin</favouritemusic>
   <favouritetvshows></favouritetvshows>
   <favouritemovies>fightclub</favouritemovies>
   <favouritebooks></favouritebooks>
   <favouritegames>ut3</favouritegames>
   <description></description>
   <profilepage>http://www.KDE-Look.org/usermanager/search.php?username=Frank</profilepage>
  </person>
 </data>
</ocs>

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.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <person details="full">
   <personid>Frank</personid>
   <privacy>1</privacy>
   <privacytext>visible only for registered users</privacytext>
   <firstname>Frank</firstname>
   <lastname>Test</lastname>
   <gender>man</gender>
   <communityrole>developer</communityrole>
   <homepage>opendesktop.org</homepage>
   <company>opendesktop.org</company>
   <avatarpic>http://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg</avatarpic>
   <avatarpicfound>1</avatarpicfound>
   <bigavatarpic>http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg</bigavatarpic>
   <bigavatarpicfound>1</bigavatarpicfound>
   <birthday>1973-07-25</birthday>
   <jobstatus>working</jobstatus>
   <city>Stuttgart</city>
   <country>Germany</country>
   <latitude></latitude>
   <longitude></longitude>
   <ircnick>karli</ircnick>
   <ircchannels>kde-dev, plasma</ircchannels>
   <irclink>irc://irc.freenode.org/kde-dev</irclink>
   <irclink>irc://irc.freenode.org/plasma</irclink>
   <likes>lot of stuff</likes>
   <dontlikes>nothing</dontlikes>
   <interests>travel</interests>
   <languages>english</languages>
   <programminglanguages>php, c++</programminglanguages>
   <favouritequote></favouritequote>
   <favouritemusic>nin</favouritemusic>
   <favouritetvshows></favouritetvshows>
   <favouritemovies>fightclub</favouritemovies>
   <favouritebooks></favouritebooks>
   <favouritegames>ut3</favouritegames>
   <description></description>
   <profilepage>http://www.KDE-Look.org/usermanager/search.php?username=Frank</profilepage>
  </person>
 </data>
</ocs>

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.

Example: POST http://frank:password@api.opendesktop.org/v1/person/self postdata: longitude="1.23" latitude="3.45" Updated my position to 1.23 and 3.45 Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
   <status>ok</status>
   <statuscode>100</statuscode>
   <message></message>
 </meta>
</ocs>

balance

Get the account balance of a user.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <person details="balance">
   <currency>USD</currency>
   <balance>1.49</balance>
  </person>
 </data>
</ocs>

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.

Example: GET http://frank:password@api.opendesktop.org/v1/person/attributes/fregl/parley/language Get the value of the key language of the application parley from the user fregl. Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>1</totalitems>
 </meta>
 <data>
  <attribute>
   <app>parley</app>
   <key>language</key>
   <value>english, german</value>
  </attribute>
 </data>
</ocs>

set attribute

Set a attribute of a person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: POST http://frank:password@api.opendesktop.org/v1/person/setattribute/parley/language postdata: value="italian" Set the value of the key "language" of the application "parley" to "italian". Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

delete attribute

Delete a attribute of a person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: POST http://frank:password@api.opendesktop.org/v1/person/deleteattribute/parley/language Delete the attribute with the key "language" and the application "parley". Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

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.

Example: GET http://frank:password@api.opendesktop.org/v1/friend/data/foobar?pagesize=10&page=1 Gets the second page of friends of the person "foobar" Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>3</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <user details="id">
   <personid>cornelius</personid>
  </user>
  <user details="id">
   <personid>dave</personid>
  </user>
  <user details="id">
   <personid>fen</personid>
  </user>
 </data>
</ocs>

receivedinvitations

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

Example: GET http://frank:password@api.opendesktop.org/v1/friend/receivedinvitations?page=1 Gets the second page of my received invitations. Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>1</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <user details="id">
   <personid>testy</personid>
  </user>
 </data>
</ocs>

sentinvitations

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

Example: GET http://frank:password@api.opendesktop.org/v1/friend/sentinvitations?page=1 Gets the second page of my sent invitations. Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>1</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <user details="id">
   <personid>testy</personid>
  </user>
 </data>
</ocs>

invite

Invite a person to become a friend. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: POST http://frank:password@api.opendesktop.org/v1/friend/invite/foobar/ postdata: message="hi. how are you?" Invites the person "foobar" and send him a message "hi. how are you?" Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

approve

Approve a friendship request. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: POST http://frank:password@api.opendesktop.org/v1/friend/approve/foobar/ Approve the invitation from the user "foobar" Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

decline

Decline a friendship request. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: POST http://frank:password@api.opendesktop.org/v1/friend/decline/foobar/ Decline the invitation from the user "foobar" Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

cancel

Cancel a friendship with a user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: POST http://frank:password@api.opendesktop.org/v1/friend/cancel/foobar/ Cancel the friendship with the user "foobar" Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

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.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>4</totalitems>
 </meta>
 <data>
  <folder>
   <id>0</id>
   <name>inbox</name>
   <messagecount>27</messagecount>
   <type>inbox</type>
  </folder>
  <folder>
   <id>1</id>
   <name>send</name>
   <messagecount>9</messagecount>
   <type>send</type>
  </folder>
  <folder>
   <id>2</id>
   <name>trash</name>
   <messagecount>0</messagecount>
   <type>trash</type>
  </folder>
  <folder>
   <id>3</id>
   <name>archive</name>
   <messagecount>0</messagecount>
   <type></type>
  </folder>
 </data>
</ocs>

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.

Example: GET http://frank:password@api.opendesktop.org/v1/message/1?page=2&pagesize=10 Gets the third page of messages from the folder with the id 1 of person "frank". firstname, lastname and profilepage are from the sender of the message. Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <message details="full">
   <id>8490</id>
   <messagefrom>testy</messagefrom>
   <firstname>Frank</firstname>
   <lastname>Karlitschek</lastname>
   <profilepage>http://www.opendesktop.org/usermanager/search.php?username=Frank</profilepage>
   <messageto>Frank</messageto>
   <senddate>2008-08-10T16:03:59+02:00</senddate>
   <status>1</status>
   <statustext></statustext>
   <subject>test message</subject>
   <body>Sorry for bothering but did you ...</body>
  </message>
  <message details="full">
   <id>8491</id>
   <messagefrom>testy1</messagefrom>
   <firstname>Testy</firstname>
   <lastname>TTT</lastname>
   <profilepage>http://www.opendesktop.org/usermanager/search.php?username=testy1</profilepage>
   <messageto>Frank1</messageto>
   <senddate>2008-08-12T16:03:59+02:00</senddate>
   <status>1</status>
   <statustext></statustext>
   <subject>test message</subject>
   <body>Testy 2 ...</body>
  </message>
 </data>
</ocs>

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.

Example: GET http://frank:password@api.opendesktop.org/v1/message/1/42 Get the message with the id 42 in the folder 1. firstname, lastname and profilepage are from the sender of the message. Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <message details="full">
   <id>8490</id>
   <messagefrom>testy</messagefrom>
   <firstname>Test</firstname>
   <lastname>TTT</lastname>
   <profilepage>http://www.opendesktop.org/usermanager/search.php?username=testy</profilepage>
   <messageto>Frank</messageto>
   <senddate>2008-08-10T16:03:59+02:00</senddate>
   <status>1</status>
   <statustext></statustext>
   <subject>test message</subject>
   <body>Sorry for bothering but did you ...</body>
  </message>
 </data>
</ocs>

send

Send a message. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

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.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <activity details="full">
   <id>42</id>
   <personid>testy2</personid>
   <firstname>Test</firstname>
   <lastname>Te</lastname>
   <profilepage>/usermanager/search.php?username=testy2</profilepage>
   <avatarpic>http://www.opendesktop.org/usermanager/nopic.png</avatarpic>
   <timestamp>2008-08-01T20:30:19+02:00</timestamp>
   <type>6</type>
   <message>testy2 has updated: &quot;Extract And Compress&quot;</message>
   <link>http://www.KDE-Look.org/content/show.php?content=84206</link>
  </activity>
  <activity details="full">
   <id>43</id>
   <personid>foobar2</personid>
   <firstname>Foo</firstname>
   <lastname>Bar</lastname>
   <profilepage>/usermanager/search.php?username=foobar2</profilepage>
   <avatarpic>http://www.opendesktop.org/usermanager/nopic.png</avatarpic>
   <timestamp>2008-08-02T19:38:10+02:00</timestamp>
   <type>6</type>
   <message>foobar2 has updated: &quot;Arezzo&quot;</message>
   <link>http://www.KDE-Look.org/content/show.php?content=84403</link>
  </activity>
 </data>
</ocs>

put

Updates your activities. This is microblogging like Twitter. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

CONTENT

categories

Get a list of all available content categories.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>4</totalitems>
 </meta>
 <data>
  <category>
   <id>1</id>
   <name>KDE Wallpaper 640x480</name>
  </category>
  <category>
   <id>2</id>
   <name>KDE Wallpaper 800x600</name>
  </category>
  <category>
   <id>3</id>
   <name>KDE Wallpaper 1024x768</name>
  </category>
  <category>
   <id>4</id>
   <name>KDE Wallpaper 1280x1024</name>
  </category>
 </data>
</ocs>

licenses

Get a list of all possible licenses.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>17</totalitems>
 </meta>
 <data>
  <license>
   <id>1000</id>
   <name></name>
   <link></link>
  </license>
  <license>
   <id>3</id>
   <name>Artistic 2.0</name>
   <link>http://dev.perl.org/perl6/rfc/346.html</link>
  </license>
  <license>
   <id>6</id>
   <name>BSD</name>
   <link>http://www.opensource.org/licenses/bsd-license.php</link>
  </license>
 </data>
</ocs>

distributions

Get a list of all possible distributions.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>23</totalitems>
 </meta>
 <data>
  <distribution>
   <id>0</id>
   <name></name>
  </distribution>
  <distribution>
   <id>2200</id>
   <name>Arch</name>
  </distribution>
  <distribution>
   <id>2000</id>
   <name>Ark</name>
  </distribution>
  <distribution>
   <id>1100</id>
   <name>Debian</name>
  </distribution>
 </data>
</ocs>

dependencies

Get a list of all possible dependencies.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>36</totalitems>
 </meta>
 <data>
  <dependtypes>
   <id>0</id>
   <name></name>
  </dependtypes>
  <dependtypes>
   <id>30</id>
   <name>GNOME 1.x</name>
  </dependtypes>
  <dependtypes>
   <id>31</id>
   <name>GNOME 2.x</name>
  </dependtypes>
  <dependtypes>
   <id>20</id>
   <name>GTK 1.x</name>
  </dependtypes>
 </data>
</ocs>

homepagetypes

Get a list of all possible homepagetypes.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>14</totalitems>
 </meta>
 <data>
  <homepagetypes>
   <id>0</id>
   <name>&amp;nbsp;</name>
  </homepagetypes>
  <homepagetypes>
   <id>10</id>
   <name>Blog</name>
  </homepagetypes>
  <homepagetypes>
   <id>20</id>
   <name>Facebook</name>
  </homepagetypes>
 </data>
</ocs>

list

Gets a list of a specific set of contents.

Example: 

<?xml version="1.0"?>

<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <content details="summary">
   <id>1420</id>
   <name>name</name>
   <version>11122</version>
   <changed>2007-11-24T22:41:08+01:00</changed>
   <created>2007-11-01T22:28:24+01:00</created>
   <typeid>6</typeid>
   <typename>KDE Wallpaper (other)</typename>
   <language></language>
   <personid>Frank</personid>
   <downloads>5</downloads>
   <score>50</score>
   <comments>0</comments>
   <preview1>http://www.KDE-Look.org/content/preview.php?preview=1&amp;id=1420&amp;file1=1420-1.png&amp;file2=1420-2.png&amp;file3=&amp;name=nameeee</preview1>
   <previewpic1>http://www.KDE-Look.org/CONTENT/content-pre1/1420-1.png</previewpic1>
  </content>
  <content details="summary">
   <id>1422</id>
   <name>testy2</name>
   <version>11</version>
   <changed>2007-11-01T22:45:20+01:00</changed>
   <created>2007-11-01T22:43:21+01:00</created>
   <typeid>7</typeid>
   <typename>KDE Wallpaper (SVG)</typename>
   <language></language>
   <personid>Frank</personid>
   <downloads>8</downloads>
   <score>50</score>
   <comments>0</comments>
   <preview1>http://www.KDE-Look.org/content/preview.php?preview=1&amp;id=1422&amp;file1=1422-1.jpg&amp;file2=1422-2.png&amp;file3=1422-3.png&amp;name=vdfdds222</preview1>
   <previewpic1>http://www.KDE-Look.org/CONTENT/content-pre1/1422-1.jpg</previewpic1>  
   <smallpreviewpic1>http://www.KDE-Look.org/CONTENT/content-m1/m1421-1.png</smallpreviewpic1>
   <downloadtype1>Fedora </downloadtype1>
   <downloadprice1>2.99</downloadprice1>
   <downloadlink1>http://www.opendesktop.org/content/buy.php?content=1422&amp;id=1</downloadlink1>
   <downloadname1>pay item 1</downloadname1>
   <downloadsize1>2</downloadsize1>
   <downloadtype2>Ubuntu </downloadtype2>
   <downloadprice2>0</downloadprice2>
   <downloadlink2>http://www.opendesktop.org/content/download.php?content=1422&amp;id=2</downloadlink2>
   <downloadname2>free download</downloadname2>
   <downloadtype3>SUSE </downloadtype3>
   <downloadprice3>0</downloadprice3>
   <downloadlink3>http://www.opendesktop.org/content/download.php?content=1422&amp;id=3</downloadlink3>
   <downloadname3>free item</downloadname3>
   <detailpage>http://www.KDE-Look.org/content/show.php?content=100</detailpage>
  </content>
 </data>
</ocs>

get

Read content data of one specific content.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <content details="full">
   <id>100</id>
   <name>GradE8</name>
   <version></version>
   <typeid>10</typeid>
   <typename>Theme/Style for KDE 2.1</typename>
   <language></language>
   <personid>Hans</personid>
   <created>2001-09-28T18:45:40+02:00</created>
   <changed>2001-09-28T18:45:40+02:00</changed>
   <downloads>2</downloads>
   <score>67</score>
   <description>his is my first KDE 2.0 theme. It isn't the final version, I must add some icons etc...</description>
   <changelog></changelog>
   <homepage>http://en.wikipedia.org/foo111</homepage>
   <homepagetype>Wikipedia</homepagetype>
   <homepage2></homepage2>
   <homepagetype2></homepagetype2>
   <homepage3>http://myhomepage.com</homepage3>
   <homepagetype3>Blog</homepagetype3>
   <homepage4></homepage4>
   <homepagetype4></homepagetype4>
   <homepage5></homepage5>
   <homepagetype5></homepagetype5>
   <homepage6></homepage6>
   <homepagetype6></homepagetype6>
   <homepage7></homepage7>
   <homepagetype7></homepagetype7>
   <homepage8></homepage8>
   <homepagetype8></homepagetype8>
   <homepage9></homepage9>
   <homepagetype9></homepagetype9>
   <homepage10></homepage10>
   <homepagetype10></homepagetype10>
   <comments>0</comments>
   <commentspage>http://www.opendesktop.org/content/show.php?content=100</commentspage>
   <fans>22</fans>
   <fanspage>http://www.opendesktop.org/content/show.php?action=fan&amp;content=100</fanspage>
   <knowledgebaseentries>7</knowledgebaseentries>
   <knowledgebasepage>http://www.opendesktop.org/content/show.php?action=knowledgebase&amp;content=100</knowledgebasepage>
   <depend></depend>
   <preview1>http://www.KDE-Look.org/content/preview.php?preview=1&amp;id=100&amp;file1=100-1.jpg&amp;file2=&amp;file3=&amp;name=GradE8</preview1>
   <preview2></preview2>
   <preview3></preview3>
   <previewpic1>http://www.KDE-Look.org/CONTENT/content-pre1/100-1.jpg</previewpic1>
   <previewpic2></previewpic2>
   <previewpic3></previewpic3>
   <smallpreviewpic1>http://www.KDE-Look.org/CONTENT/content-m1/m100-1.png</smallpreviewpic1>
   <smallpreviewpic2></smallpreviewpic2>
   <smallpreviewpic3></smallpreviewpic3>
   <detailpage>http://www.KDE-Look.org/content/show.php?content=100</detailpage>
   <downloadtype1>Fedora </downloadtype1>
   <downloadprice1>0</downloadprice1>
   <downloadlink1>http://www.opendesktop.org/content/download.php?content=1423&amp;id=2</downloadlink1>
   <downloadname1>gdfgd22</downloadname1>
   <downloadsize1>2</downloadsize1>
   <downloadtype2>Fedora </downloadtype2>
   <downloadprice2>2.99</downloadprice2>
   <downloadlink2>http://www.opendesktop.org/content/buy.php?content=1423&amp;id=1</downloadlink2>
   <downloadname2>gdgg22</downloadname2>
  </content>
 </data>
</ocs>

download

Download or buy one specific content item.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <content details="download">
   <downloadlink>http://www......tar.gz</downloadlink>
  </content>
 </data>
</ocs>

vote

Vote for one specific content.

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

add

Add a new content entry:

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <content>
   <id>1234567</id>
  </content>
 </data>
</ocs>

edit

Edit a content entry:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete content entry

Delete a content entry:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

upload new download file

Upload a new download file to a content:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete download file

Delete the download file from a content:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

upload preview image

Upload a new preview image for a content:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete preview image

Delete a preview image from a content:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

FAN

get

Gets a list of fans of a specific content entries. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <fan details="fans">
   <personid>Frank</personid>
   <timestamp>2009-08-18T10:40:09+02:00</timestamp>
  </fan>
  <fan details="fans">
   <personid>Test</personid>
   <timestamp>2009-07-18T11:41:15+02:00</timestamp>
  </fan>
 </data>
</ocs>

isfan

Check if the current user is fan of a specific content. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <status>fan</status>
 </data>
</ocs>

add

Become a fan of a specific content. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

remove

Remove the user from the fans list of a specific content. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

KNOWLEDGEBASE

list

Gets a list of a specific set of knowledgebase entries. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <content details="detail">
   <id>1</id>
   <status>not answered</status>
   <contentid>12345</contentid>
   <category>Application</category>
   <user>testy</user>
   <changed>2009-02-07T23:14:11+01:00</changed>
   <name>app question</name>
   <description>How can I ........</description>
   <answer></answer>
   <answeruser>testy2</answeruser>
   <comments>0</comments>
   <detailpage>http://www.opendesktop.org/content/show.php?action=knowledgebase&amp;content=11&amp;kbid=12345</detailpage>
  </content>
  <content details="detail">>
   <id>2</id>
   <status>answered</status>
   <contentid>12345</contentid>
   <category>other</category>
   <user>testy</user>
   <changed>2009-02-03T21:11:01+01:00</changed>
   <name>app question 22</name>
   <description>How can I 22........</description>
   <answeruser>testy2</answeruser>
   <answer></answer>
   <comments>0</comments>
   <detailpage>http://www.opendesktop.org/content/show.php?action=knowledgebase&amp;content=11&amp;kbid=12</detailpage>
  </content>
 </data>

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.

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <knowledgebase>
   <id>1</id>
   <status>not answered</status>
   <contentid>12345</contentid>
   <category>Application</category>
   <user>testy</user>
   <changed>2009-02-07T23:14:11+01:00</changed>
   <name>app question</name>
   <description>How can I ........</description>
   <answeruser>testy2</answeruser>
   <answer></answer>
   <comments>0</comments>
   <detailpage>http://www.opendesktop.org/content/show.php?action=knowledgebase&amp;content=11&amp;kbid=12345</detailpage>
  </knowledgebase>
 </data>
</ocs>

EVENT

list

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

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <event details="detail">
   <id>4</id>
   <name>Test Party</name>
   <category>Party</category>
   <startdate>2010-08-02T00:00:00+02:00</startdate>
   <enddate>2011-10-03T00:00:00+02:00</enddate>
   <user>Frank</user>
   <city>Stuttgart</city>
   <country>Germany</country>
   <longitude>9.183</longitude>
   <latitude>48.767</latitude>
   <changed>2009-05-18T14:03:55+02:00</changed>
   <comments>2</comments>
   <participants>2</participants>
   <badge></badge>
   <detailpage>http://www.opendesktop.org/events/?id=4</detailpage>
  </event>
  <event details="detail">
   <id>3</id>
   <name>Another Party</name>
   <category>Party</category>
   <startdate>1979-01-01T01:00:01+01:00</startdate>
   <enddate>1979-01-01T01:00:01+01:00</enddate>
   <user>Frank</user>
   <city>Stuttgart</city>
   <country>Germany</country>
   <longitude>1.2</longitude>
   <latitude>1.1</latitude>
   <changed>2009-05-16T00:25:31+02:00</changed>
   <comments>0</comments>
   <participants>1</participants>
   <badge></badge>
   <detailpage>http://www.opendesktop.org/events/?id=3</detailpage>
  </event>
 </data>
</ocs>

get

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

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <event>
   <id>6</id>
   <name>bbb</name>
   <description>here is the description text</description>
   <category>Party</category>
   <startdate>1970-01-01T00:00:00+01:00</startdate>
   <enddate>1970-01-01T00:00:00+01:00</enddate>
   <user>Frank</user>
   <organizer></organizer>
   <location></location>
   <city></city>
   <country>Germany</country>
   <longitude>0</longitude>
   <latitude>0</latitude>
   <homepage></homepage>
   <tel></tel>
   <fax></fax>
   <email></email>
   <changed>2009-05-18T18:49:15+02:00</changed>
   <comments>1</comments>
   <participants>2</participants>
   <detailpage>http://www.opendesktop.org/events/?id=6</detailpage>
   <badge>http://www.opendesktop.org/CONTENT/event-badge/0/6.png</badge>
   <image></image>
  </event>
 </data>
</ocs>

add

Add a new event entry:

Example: 

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <event>
   <id>1234567</id>
  </event>
 </data>
</ocs>

edit

Edit a event entry:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete event entry

Delete a event entry:

Example: 

<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

CategoryHomepage