RESTful open-collaboration-services

open collaboration services.md

Open Collaboration Services v1.7

This is a draft for the upcoming version 1.7

[Frank Karlitschek](mailto:karlitschek AT kde.org)

OCS Mailinglist

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:

• voting PRIVATEDATA:

• new module FORUM:

• new module BUILDSERVICE:

• new module Differences between 1.6 and 1.1 CLOUD

• new module

Purpose

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

Examples

• show all my friends on my desktop and make it possible to contact them via email, messaging, instant messaging, screensharing or other.
• find online support information and show them directly in the application
• show other people with similar interests or from the same city and enable filesharing and collaboration
• show the activities of my friends on my desktop
• show related free software events in my region in my calendar.
• make it possible for a person to become a "friend" of a developer and a fan of an application
• find other people to work together on one document. (collaboration)
• find other people with the same hardware to get help and exchange tips.
• show kde related and personalized news directly on the desktop

Naming

• client - the desktop or mobile application, web frontend or proxy who access the services.
• service provider - web bases application, webservices or online communities who provide open collaboration services.
• 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

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:

• 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:

<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

GET /v1/config 

• Statuscodes: * 100 - successful Example:

$ curl http://api.opendesktop.org/v1/config
<?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.

POST /v1/person/check 

• POST Arguments: login - The login or the API key
• POST Arguments: password - The password
• Mandatory fields: "login"
• Statuscodes: * 100 - successfull / valid account * 101 - please specify all mandatory fields * 102 - login not valid Example, check if frank:123456 is a valid account:

$ curl -X POST -d "login=frank" -d "password=123456" http://api.opendesktop.org/v1/person/check
<?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. Only alphanumeric characters are allowed and the password has to be 8 characters or longer.

POST /v1/person/add 

• 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.
• Mandatory fields: "login", "password", "firstname", "lastname" and "email"
• Statuscodes: * 100 - successfull / valid account * 101 - please specify all mandatory fields * 102 - please specify a valid password * 103 - please specify a valid login * 104 - login already exists * 105 - email already taken * 106 - email invalid Example, register a new user account:

$ curl -X POST http://api.opendesktop.org/v1/person/add -d "login=frank" -d "password=123456" -d "lastname=Karlitschek" -d "email=karlitschek@kde.org"
<?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.

GET /v1/person/data 

• 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.
• Result: personlist xml Example - get 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:

$ curl -u frank:password http://api.opendesktop.org/v1/person/data?name=eter&city=don&description=development&latitude=11.2&longitude=22&distance=0.5&page=2&pagesize=10
<?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>male</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.

GET /v1/person/data/:personid

• Path parameter: personid - Id of a person, for example "frank"
• Result: person xml
• Statuscodes: * 100 - successfull * 101 - person not found * 102 - data is private
• Example:

$ curl -u frank:password http://api.opendesktop.org/v1/person/data/frank
<?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>male</gender>
   <communityrole>developer</communityrole>
   <homepage>openDesktop.org</homepage>
   <homepagetype></homepagetype>
   <homepageicon></homepageicon>
   <homepage2></homepage2>
   <homepagetype2></homepagetype2>
   <homepage3></homepage3>
   <homepagetype3></homepagetype3>
   <homepage4></homepage4>
   <homepagetype4></homepagetype4>
   <homepageicon4></homepageicon4>
   <homepage5></homepage5>
   <homepagetype5></homepagetype5>
   <homepage6>www.facebook.com/foo</homepage6>
   <homepagetype6>Facebook</homepagetype6>
   <homepageicon6>http://openDesktop.org/img/socialicons/emblem-facebook.png</homepageicon6>
   <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.

GET /v1/person/self 

• Result: person xml
• Statuscodes: * 100 - successfull
• Example:

$ curl -u frank:password http://api.opendesktop.org/v1/person/self
<?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>male</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.

POST /v1/person/self

• POST Arguments: latitude - The latitude of myself
• POST Arguments: longitude - The longitude of myself
• POST Arguments: city - Your city
• POST Arguments: country - The 2 letter ISO country code
• Statuscodes: * 100 - successfull * 101 - no parameters to update found Example - update my position to 1.23 and 3.45:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/person/self -d "longitude=1.23" -d "latitude=3.45"
<?xml version="1.0"?>
<ocs>
 <meta>
   <status>ok</status>
   <statuscode>100</statuscode>
   <message></message>
 </meta>
</ocs>

balance

Get the account balance of a user.

GET /v1/person/balance 

• Result: status xml
• Example:

$ curl http://api.opendesktop.org/v1/person/balance
<?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.

GET /v1/person/attributes/:personid/:app/:key

• 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.
• Statuscodes: * 100 - successfull Example - get the value of the key language of the application parley from the user 'fregl':

$ curl http://frank:password@api.opendesktop.org/v1/person/attributes/fregl/parley/language
<?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>
   <lastmodified>2007-11-01T22:45:20+01:00</lastmodified>
  </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.

POST /v1/person/setattribute/:app/:key

• Arguments: app - The application where you want to store this attribute at.
• Arguments: key - The key of the attribute.
• POST arguments: value - The value of the attribute.
• Statuscodes: * 100 - successfull Example - set the value of the key "language" of the application "parley" to "italian".

$ curl -X POST http://frank:password@api.opendesktop.org/v1/person/setattribute/parley/language -d "value=italian"
<?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.

POST /v1/person/deleteattribute/:app/:key

• Arguments: app - The application where the key is stored.
• Arguments: key - The key of the attribute.
• Statuscodes: * 100 - successfull Example - delete the attribute with the key "language" and the application "parley". FIXME make RESTful

$ curl -X POST http://frank:password@api.opendesktop.org/v1/person/deleteattribute/parley/language
<?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.

GET /v1/friend/data/:personid

• 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, ...
• URL Arguments: pagesize - The amount of entries per page.
• Statuscodes: * 100 - successfull * 101 - data is private * 102 - user not found Example - get the second page of friends of the person "foobar":

$ curl http://frank:password@api.opendesktop.org/v1/friend/data/foobar?pagesize=10&page=1
<?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.

GET /v1/friend/receivedinvitations

• URL Arguments: page - The page of the list. The size of a page is controlled by the pagesize argument. The first page is 0, the second is 1, ...
• URL Arguments: pagesize - The amount of entries per page.
• Statuscodes: * 100 - successfull Example - get the second page of my received invitations.

$ curl http://frank:password@api.opendesktop.org/v1/friend/receivedinvitations?page=1
<?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.

GET /v1/friend/sentinvitations

• URL Arguments: page - The page of the list. The size of a page is controlled by the pagesize argument. The first page is 0, the second is 1, ...
• URL Arguments: pagesize - The amount of entries per page.
• Statuscodes: * 100 - successfull Example - get the second page of my sent invitations:

$ curl http://frank:password@api.opendesktop.org/v1/friend/sentinvitations?page=1
<?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.

POST /v1/friend/invite/:personid

• Arguments: personid - The person you want to invite as a friend.
• POST arguments: message - The message you want to send to the person together with your invitation.
• Statuscodes: * 100 - successfull * 101 - message must not be empty * 102 - you can´t invite yourself * 103 - user not found Example - invite the person "foobar" and send him a message "hi. how are you?":

$ curl -X POST http://frank:password@api.opendesktop.org/v1/friend/invite/foobar/ -d "message=hi. how are you?"
<?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.

POST /v1/friend/approve/:personid

• Arguments: personid - The person you want to approve as a friend.
• Statuscodes: * 100 - successful Example - approve the invitation from the user "foobar":

$ curl -X POST http://frank:password@api.opendesktop.org/v1/friend/approve/foobar/
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

decline

FIXME reject instead of decline?

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

POST /v1/friend/decline/:personid

• Arguments: personid - The person you want to decline.
• Statuscodes: * 100 - successful Example - decline the invitation from the user "foobar":

$ curl -X POST http://frank:password@api.opendesktop.org/v1/friend/decline/foobar/
<?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.

POST /v1/friend/cancel/:personid

• Arguments: personid - The person you want to cancel the friendship with.
• Statuscodes: * 100 - successful Example - cancel the friendship with the user "foobar":

$ curl -X POST http://frank:password@api.opendesktop.org/v1/friend/cancel/foobar/
<?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.

GET /v1/message

• Result: messagefolder xml
• Statuscodes: * 100 - successfull
• Example:

$ curl http://frank:password@api.opendesktop.org/v1/message
<?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.

GET /v1/message/:folder

• Path parameter: folder - The ID of the folder you want to get. Use the folders method to get the list of folders.
• Query parameter: status - Show only messages with the specified status. Possible values are: 0-unread, 1-read, 2-replyed
• Query parameter: page - The content page. The amount of entries can be controlled by the pagesize argument. The first page is 0, the second is 1, ...
• URL Arguments: pagesize - The amount of entries per page.
• Result: messagelist xml * Status: 0 - unread * Status: 1 - read * Status: 2 - answered
• Statuscodes: * 100 - successfull Example - get 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:

$ curl http://frank:password@api.opendesktop.org/v1/message/1?page=2&pagesize=10
<?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.

GET /v1/message/:folderid/:messageid

• Path parameter: folderid - The ID of the folder. Use the folders method to get the list of folders.
• Path parameter: messageid - The ID of the message you want to get.
• Result: message xml * Status: 0 - unread * Status: 1 - read * Status: 2 - answered
• Statuscodes: * 100 - successful * 101 - message not found Example - get the message with the id 42 in the folder 1. firstname, lastname and profilepage are from the sender of the message:

$ curl http://frank:password@api.opendesktop.org/v1/message/1/42 
<?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.

POST /v1/message/:sendfolder

• POST Arguments: to - The receiver of the message.
• POST Arguments: subject - The subject of the message.
• POST Arguments: message - The text you want to send.
• Result: status xml
• Statuscodes: * 100 - successfull * 101 - user not found * 102 - subject or message not found * 103 - you can not send a message to yourself.
• Example - send a message to "frank" with the subject "hello" and a messagebody "coding is fun":

$ curl -X POST http://frank:password@api.opendesktop.org/v1/message/2 -d "message=coding is fun" -d "subject=hello" -d "to=frank"
<?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.

GET /v1/activity

• 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, ...
• URL Arguments: pagesize - The amount of entries per page.
• Result: activities xml
• type categories: * 1 - status message * 2 - new friend * 3 - new content upload * 4 - profile update * 5 - profile photo update * 6 - content edit * 7 - new message * 8 - homepage visit * 9 - become fan * 10 - no longer fan * 11 - group created * 12 - group joined * 13 - group left * 14 - event created * 15 - attending the event * 16 - no longer attending the event * 17 - created the job offer * 18 - edited the job offer * 19 - has registered (new user)
• Statuscodes: * 100 - successfull
• Example - get the third page of the activities of person "frank":

$ curl http://frank:password@api.opendesktop.org/v1/activity?page=3&pagesize=10
<?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.

POST /v1/activity

• POST Arguments: message - The text you want to post.
• Result: status xml
• Statuscodes: * 100 - successful * 101 - empty message * 102 - user not found Example - post the text "coding is fun" to franks hompage and the activities of franks friends:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/activity -d "message=coding is fun" 
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

CONTENT

categories

Get a list of all available content categories.

GET /v1/content/categories

• Result: categories xml
• Statuscodes: * 100 - successful * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl http://frank:password@api.opendesktop.org/v1/content/categories
<?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. The IDs can be alphanumeric. The IDs should follow "liblicense" if possible.

GET /v1/content/licenses

• Result: categories xml
• Statuscodes: * 100 - successful * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl http://frank:password@api.opendesktop.org/v1/content/licenses
<?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. The IDs can be alphanumeric.

GET /v1/content/distributions

• Result: categories xml
• Statuscodes: * 100 - successful * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl http://frank:password@api.opendesktop.org/v1/content/distributions
<?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.

GET /v1/content/dependencies

• Result: categories xml
• Statuscodes: * 100 - successful * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl http://frank:password@api.opendesktop.org/v1/content/dependencies
<?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.

GET /v1/content/homepages

• Result: categories xml
• Statuscodes: * 100 - successful * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl http://frank:password@api.opendesktop.org/v1/content/homepages
<?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.

GET /v1/content/data/

• URL Arguments: categories - Ids of the requested category ids seperated by "x".
• URL Arguments: search - the part of the name of the item you want to find.
• URL Arguments: user - show only contents from one specific user.
• URL Arguments: external - if set external=off only contents which are hosted on the same server are shown
• URL Arguments: distribution - show only content which is supported by this distributions. the parameter is a comma seperated list of ids as returned by the "distribution" method
• URL Arguments: license - show only content which is available under a specific license. the parameter is a comma seperated list of ids as returned by the "license" method
• URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest first , "alpha" - alphabetical, "high" - highest rated, "down" - most downloads
• URL Arguments: page - The content page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ...
• URL Arguments: pagesize - The amount of entries per page.
• Result: content xml
• Statuscodes: * 100 - successful * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example - get the second page of the list of the newest contents from categories 1,2,3 and 4 with the string foo in the name:

$ curl http://frank:password@api.opendesktop.org/v1/content/data?categories=1x2x3x4&search=foo&sortmode=new&page=1
<?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>
   <profilepage>http://www.opendesktop.org/usermanager/search.php?username=Frank</profilepage>
   <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>
   <summary>this is a short summary</summary>
   <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>
   <icon width="16" height="16">http://www.KDE-Look.org/img/icon1.png</icon>
   <icon width="32" height="32">http://www.KDE-Look.org/img/icon2.png</icon>
   <icon width="64" height="64">http://www.KDE-Look.org/img/icon2.png</icon>
   <smallpreviewpic1>http://www.KDE-Look.org/CONTENT/content-m1/m1421-1.png</smallpreviewpic1>
   <downloadway1>1</downloadway1>
   <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>
   <downloadgpgsignature1></downloadgpgsignature1>
   <downloadgpgfingerprint1></downloadgpgfingerprint1>
   <downloadtype2>Ubuntu </downloadtype2>
   <downloadprice2>0</downloadprice2>
   <downloadlink2>http://www.opendesktop.org/content/download.php?content=1422&amp;id=2</downloadlink2>
   <downloadname2>free download</downloadname2>
   <downloadgpgsignature2></downloadgpgsignature2>
   <downloadgpgfingerprint2></downloadgpgfingerprint2>
   <downloadtype3>SUSE </downloadtype3>
   <downloadprice3>0</downloadprice3>
   <downloadlink3>http://www.opendesktop.org/content/download.php?content=1422&amp;id=3</downloadlink3>
   <downloadname3>free item</downloadname3>
   <downloadgpgsignature3></downloadgpgsignature3>
   <downloadgpgfingerprint3></downloadgpgfingerprint3>
   <detailpage>http://www.KDE-Look.org/content/show.php?content=100</detailpage>
  </content>
 </data>
</ocs>

get

Read content data of one specific content.

GET /v1/content/data/:contentid

• Arguments: contentid - Id of a content
• Result: content xml
• Statuscodes: * 100 - successfull * 101 - content not found * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl http://frank:password@api.opendesktop.org/v1/content/data/12345
<?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>
   <summary>this is a short summary</summary>
   <changelog></changelog>
   <feedbackurl>http://openDesktop.org/feedback</feedbackurl>
   <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>
   <donationpage>http://www.opendesktop.org/content/donation.php?content=123</donationpage>
   <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>
   <icon width="16" height="16">http://www.KDE-Look.org/img/icon1.png</icon>
   <icon width="32" height="32">http://www.KDE-Look.org/img/icon2.png</icon>
   <icon width="64" height="64">http://www.KDE-Look.org/img/icon2.png</icon>
   <video>http://www.KDE-Look.org/video/video1.mpg</video>
   <video>http://www.KDE-Look.org/video/video2.mpg</video>
   <video>http://www.KDE-Look.org/video/video3.mpg</video>
   <detailpage>http://www.KDE-Look.org/content/show.php?content=100</detailpage>
   <downloadway1>1</downloadway1>
   <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>
   <downloadgpgfingerprint1>6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D</downloadgpgfingerprint1>
   <downloadgpgsignature1>iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy</downloadgpgsignature1>
   <downloadpackagename1>packname</downloadpackagename1>
   <downloadrepository1>repo</downloadrepository1>
   <downloadtype2>Fedora </downloadtype2>
   <downloadprice2>2.99</downloadprice2>
   <downloadlink2>http://www.opendesktop.org/content/buy.php?content=1423&amp;id=1</downloadlink2>
   <downloadname2>gdgg22</downloadname2>
   <downloadgpgfingerprint2>6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D</downloadgpgfingerprint2>
   <downloadgpgsignature2>iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy</downloadgpgsignature2>
   <downloadpackagename2>packname</downloadpackagename2>
   <downloadrepository2>repo</downloadrepository2>
  </content>
 </data>
</ocs>

download

Download or buy one specific content item. links to the package and links to repositories are supported. You get the dowloadlink or the packagename/packagerepository comination in the XML.

GET /v1/content/download/:contentid/:itemid

• Arguments: contentid - Id of a content
• Arguments: itemid - Id of a content
• Result: status xml
• Statuscodes: * 100 - successfull * 101 - content not found * 102 - payment failed * 103 - content item not found * 104 - please login to buy this content * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl http://api.opendesktop.org/v1/content/download/12345/2
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <content details="download">
   <downloadway>0</downloadway>
   <downloadlink>http://www......tar.gz</downloadlink>
   <mimetype>image/jpeg</mimetype>
   <packagename>glibc-2.10.1-10.4.i686.rpm</packagename>
   <packagerepository>http://download.opensuse.org/distribution/11.2/repo/oss/</packagerepository>
   <gpgfingerprint>6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D</gpgfingerprint>
   <gpgsignature>iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy</gpgsignature>
  </content>
 </data>
</ocs>

vote

Vote for one specific content.

POST /v1/content/vote/:contentid

• Arguments: contentid - Id of a content
• POST Arguments: vote - The vote. "good" or "bad" (deprecated) or an integer between 0 to 100. 0 equals bad and 100 equals good
• Result: status xml
• Statuscodes: * 100 - successful * 101 - content not found * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/vote/12345 -d "vote=good" 
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

add

Add a new content entry:

POST v1/content/add

• POST Arguments: name - the name of the entry
• POST Arguments: type - the type or category of the entry. call the categories method to get a list of all categories.
• POST Arguments: depend - the dependency of this entry. get the possible values by calling /v1/content/dependencies
• POST Arguments: downloadtyp1 - the type of the first download. possible values are: 0 - use the uploaded file, 1 - use the downloadlink1, 2 - use downloadpackagename and downloadrepository
• POST Arguments: downloadname1 - the name of the 1. downloadlink
• POST Arguments: downloadlink1 - the url of the downloadlink
• POST Arguments: downloaddistributiontype1 - the type of the distribution for the download. call /v1/content/distributions for a list of possible options
• POST Arguments: downloadbuy1 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason1 - the description why is content is not for free.
• POST Arguments: downloadbuyprice1 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint1 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature1 - the gpg signature of this download
• POST Arguments: downloadpackagename1 - the name of the package in the repository
• POST Arguments: downloadpackagerepository1 - the repository where the package is located
• POST Arguments: downloadname2 - the name of the downloadlink
• POST Arguments: downloadlink2 - the url of the downloadlink
• POST Arguments: downloaddistributiontype2 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy2 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason2 - the description why is content is not for free.
• POST Arguments: downloadbuyprice2 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint2 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature2 - the gpg signature of this download
• POST Arguments: downloadpackagename2 - the name of the package in the repository
• POST Arguments: downloadpackagerepository2 - the repository where the package is located
• POST Arguments: downloadname3 - the name of the downloadlink
• POST Arguments: downloadlink3 - the url of the downloadlink
• POST Arguments: downloaddistributiontype3 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy3 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason3 - the description why is content is not for free.
• POST Arguments: downloadbuyprice3 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint3 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature3 - the gpg signature of this download
• POST Arguments: downloadpackagename3 - the name of the package in the repository
• POST Arguments: downloadpackagerepository3 - the repository where the package is located
• POST Arguments: downloadname4 - the name of the downloadlink
• POST Arguments: downloadlink4 - the url of the downloadlink
• POST Arguments: downloaddistributiontype4 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy4 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason4 - the description why is content is not for free.
• POST Arguments: downloadbuyprice4 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint4 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature4 - the gpg signature of this download
• POST Arguments: downloadpackagename4 - the name of the package in the repository
• POST Arguments: downloadpackagerepository4 - the repository where the package is located
• POST Arguments: downloadname5 - the name of the downloadlink
• POST Arguments: downloadlink5 - the url of the downloadlink
• POST Arguments: downloaddistributiontype5 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy5 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason5 - the description why is content is not for free.
• POST Arguments: downloadbuyprice5 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint5 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature5 - the gpg signature of this download
• POST Arguments: downloadpackagename5 - the name of the package in the repository
• POST Arguments: downloadpackagerepository5 - the repository where the package is located
• POST Arguments: downloadname6 - the name of the downloadlink
• POST Arguments: downloadlink6 - the url of the downloadlink
• POST Arguments: downloaddistributiontype6 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy6 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason6 - the description why is content is not for free.
• POST Arguments: downloadbuyprice6 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint6 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature5 - the gpg signature of this download
• POST Arguments: downloadpackagename6 - the name of the package in the repository
• POST Arguments: downloadpackagerepository6 - the repository where the package is located
• POST Arguments: downloadname7 - the name of the downloadlink
• POST Arguments: downloadlink7 - the url of the downloadlink
• POST Arguments: downloaddistributiontype7 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy7 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason7 - the description why is content is not for free.
• POST Arguments: downloadbuyprice7 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint7 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature7 - the gpg signature of this download
• POST Arguments: downloadpackagename7 - the name of the package in the repository
• POST Arguments: downloadpackagerepository7 - the repository where the package is located
• POST Arguments: downloadname8 - the name of the downloadlink
• POST Arguments: downloadlink8 - the url of the downloadlink
• POST Arguments: downloaddistributiontype8 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy8 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason8 - the description why is content is not for free.
• POST Arguments: downloadbuyprice8 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint8 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature8 - the gpg signature of this download
• POST Arguments: downloadpackagename8 - the name of the package in the repository
• POST Arguments: downloadpackagerepository8 - the repository where the package is located
• POST Arguments: downloadname9 - the name of the downloadlink
• POST Arguments: downloadlink9 - the url of the downloadlink
• POST Arguments: downloaddistributiontype9 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy9 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason9 - the description why is content is not for free.
• POST Arguments: downloadbuyprice9 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint9 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature9 - the gpg signature of this download
• POST Arguments: downloadpackagename9 - the name of the package in the repository
• POST Arguments: downloadpackagerepository9 - the repository where the package is located
• POST Arguments: downloadname10 - the name of the downloadlink
• POST Arguments: downloadlink10 - the url of the downloadlink
• POST Arguments: downloaddistributiontype10 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy10 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason10 - the description why is content is not for free.
• POST Arguments: downloadbuyprice10 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint10 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature10 - the gpg signature of this download
• POST Arguments: downloadpackagename10 - the name of the package in the repository
• POST Arguments: downloadpackagerepository10 - the repository where the package is located
• POST Arguments: downloadname11 - the name of the downloadlink
• POST Arguments: downloadlink11 - the url of the downloadlink
• POST Arguments: downloaddistributiontype11 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy11 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason11 - the description why is content is not for free.
• POST Arguments: downloadbuyprice11 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint11 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature11 - the gpg signature of this download
• POST Arguments: downloadpackagename11 - the name of the package in the repository
• POST Arguments: downloadpackagerepository11 - the repository where the package is located
• POST Arguments: downloadname12 - the name of the downloadlink
• POST Arguments: downloadlink12 - the url of the downloadlink
• POST Arguments: downloaddistributiontype12 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy12 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason12 - the description why is content is not for free.
• POST Arguments: downloadbuyprice12 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint12 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature12 - the gpg signature of this download
• POST Arguments: downloadpackagename12 - the name of the package in the repository
• POST Arguments: downloadpackagerepository12 - the repository where the package is located
• POST Arguments: description - a description text of the entry
• POST Arguments: summary - a short summary of the entry
• POST Arguments: licensetype - the license this content is under. get the possible values by calling /v1/content/licenses
• POST Arguments: license - the license text
• POST Arguments: feedbackurl - a link to the page where users can post feedback
• POST Arguments: homepage - a link to the homepage of the entry
• POST Arguments: homepagetype - the type of the link. get the possible values by calling /v1/content/homepages
• POST Arguments: homepage2 - a link to the homepage of the entry
• POST Arguments: homepagetype2 - the type of the link.
• POST Arguments: homepage3 - a link to the homepage of the entry
• POST Arguments: homepagetype3 - the type of the link.
• POST Arguments: homepage4 - a link to the homepage of the entry
• POST Arguments: homepagetype4 - the type of the link.
• POST Arguments: homepage5 - a link to the homepage of the entry
• POST Arguments: homepagetype5 - the type of the link.
• POST Arguments: homepage6 - a link to the homepage of the entry
• POST Arguments: homepagetype6 - the type of the link.
• POST Arguments: homepage7 - a link to the homepage of the entry
• POST Arguments: homepagetype7 - the type of the link.
• POST Arguments: homepage8 - a link to the homepage of the entry
• POST Arguments: homepagetype8 - the type of the link.
• POST Arguments: homepage9 - a link to the homepage of the entry
• POST Arguments: homepagetype9 - the type of the link.
• POST Arguments: homepage10 - a link to the homepage of the entry
• POST Arguments: homepagetype10 - the type of the link.
• POST Arguments: video1 - a link to the video file
• POST Arguments: video2 - a link to the video file
• POST Arguments: video3 - a link to the video file
• POST Arguments: version - the version of this entry
• POST Arguments: changelog - the changelog of this entry
• POST Arguments: donation - do you want donation for this entry? possible values are "yes" or "" for no donation.
• POST Arguments: donationreason - a reason we you want a donation
• POST Arguments: osbsproject - the opensuse build service project id
• POST Arguments: osbspackage - the opensuse build service package id
• Result: status xml
• Mandatory fields: "name" and "type" are mandatory fields
• Statuscodes: * 100 - successful * 101 - please specify all mandatory fields * 102 - no permission to change content
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/add -d "..." TODO better 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:

POST v1/content/edit/:contentid

• POST Arguments: name - the name of the entry
• POST Arguments: type - the type or category of the entry. call the categories method to get a list of all categories.
• POST Arguments: depend - the dependency of this entry. get the possible dependencies by calling /v1/content/dependencies
• POST Arguments: downloadtyp1 - the type of the first download. possible values are: 0 - use the uploaded file, 1 - use the downloadlink1, 2 - use the downloadpackagename and downloadrepository
• POST Arguments: downloadname1 - the name of the 1. downloadlink
• POST Arguments: downloadlink1 - the url of the downloadlink
• POST Arguments: downloaddistributiontype1 - the type of the distribution for the download. get the possible distributions by calling /v1/content/distributions
• POST Arguments: downloadbuy1 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason1 - the description why is content is not for free.
• POST Arguments: downloadbuyprice1 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint1 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature1 - the gpg signature of this download
• POST Arguments: downloadpackagename1 - the name of the package in the repository
• POST Arguments: downloadpackagerepository1 - the repository where the package is located
• POST Arguments: downloadname2 - the name of the downloadlink
• POST Arguments: downloadlink2 - the url of the downloadlink
• POST Arguments: downloaddistributiontype2 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy2 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason2 - the description why is content is not for free.
• POST Arguments: downloadbuyprice2 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint2 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature2 - the gpg signature of this download
• POST Arguments: downloadpackagename2 - the name of the package in the repository
• POST Arguments: downloadpackagerepository2 - the repository where the package is located
• POST Arguments: downloadname3 - the name of the downloadlink
• POST Arguments: downloadlink3 - the url of the downloadlink
• POST Arguments: downloaddistributiontype3 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy3 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason3 - the description why is content is not for free.
• POST Arguments: downloadbuyprice3 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint3 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature3 - the gpg signature of this download
• POST Arguments: downloadpackagename3 - the name of the package in the repository
• POST Arguments: downloadpackagerepository3 - the repository where the package is located
• POST Arguments: downloadname4 - the name of the downloadlink
• POST Arguments: downloadlink4 - the url of the downloadlink
• POST Arguments: downloaddistributiontype4 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy4 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason4 - the description why is content is not for free.
• POST Arguments: downloadbuyprice4 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint4 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature4 - the gpg signature of this download
• POST Arguments: downloadpackagename4 - the name of the package in the repository
• POST Arguments: downloadpackagerepository4 - the repository where the package is located
• POST Arguments: downloadname5 - the name of the downloadlink
• POST Arguments: downloadlink5 - the url of the downloadlink
• POST Arguments: downloaddistributiontype5 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy5 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason5 - the description why is content is not for free.
• POST Arguments: downloadbuyprice5 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint5 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature5 - the gpg signature of this download
• POST Arguments: downloadpackagename5 - the name of the package in the repository
• POST Arguments: downloadpackagerepository5 - the repository where the package is located
• POST Arguments: downloadname6 - the name of the downloadlink
• POST Arguments: downloadlink6 - the url of the downloadlink
• POST Arguments: downloaddistributiontype6 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy6 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason6 - the description why is content is not for free.
• POST Arguments: downloadbuyprice6 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint6 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature6 - the gpg signature of this download
• POST Arguments: downloadpackagename6 - the name of the package in the repository
• POST Arguments: downloadpackagerepository6 - the repository where the package is located
• POST Arguments: downloadname7 - the name of the downloadlink
• POST Arguments: downloadlink7 - the url of the downloadlink
• POST Arguments: downloaddistributiontype7 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy7 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason7 - the description why is content is not for free.
• POST Arguments: downloadbuyprice7 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint7 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature7 - the gpg signature of this download
• POST Arguments: downloadpackagename7 - the name of the package in the repository
• POST Arguments: downloadpackagerepository7 - the repository where the package is located
• POST Arguments: downloadname8 - the name of the downloadlink
• POST Arguments: downloadlink8 - the url of the downloadlink
• POST Arguments: downloaddistributiontype8 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy8 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason8 - the description why is content is not for free.
• POST Arguments: downloadbuyprice8 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint8 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature8 - the gpg signature of this download
• POST Arguments: downloadpackagename8 - the name of the package in the repository
• POST Arguments: downloadpackagerepository8 - the repository where the package is located
• POST Arguments: downloadname9 - the name of the downloadlink
• POST Arguments: downloadlink9 - the url of the downloadlink
• POST Arguments: downloaddistributiontype9 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy9 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason9 - the description why is content is not for free.
• POST Arguments: downloadbuyprice9 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint9 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature9 - the gpg signature of this download
• POST Arguments: downloadpackagename9 - the name of the package in the repository
• POST Arguments: downloadpackagerepository9 - the repository where the package is located
• POST Arguments: downloadname10 - the name of the downloadlink
• POST Arguments: downloadlink10 - the url of the downloadlink
• POST Arguments: downloaddistributiontype10 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy10 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason10 - the description why is content is not for free.
• POST Arguments: downloadbuyprice10 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint10 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature10 - the gpg signature of this download
• POST Arguments: downloadpackagename10 - the name of the package in the repository
• POST Arguments: downloadpackagerepository10 - the repository where the package is located
• POST Arguments: downloadname11 - the name of the downloadlink
• POST Arguments: downloadlink11 - the url of the downloadlink
• POST Arguments: downloaddistributiontype11 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy11 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason11 - the description why is content is not for free.
• POST Arguments: downloadbuyprice11 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint11 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature11 - the gpg signature of this download
• POST Arguments: downloadpackagename11 - the name of the package in the repository
• POST Arguments: downloadpackagerepository11 - the repository where the package is located
• POST Arguments: downloadname12 - the name of the downloadlink
• POST Arguments: downloadlink12 - the url of the downloadlink
• POST Arguments: downloaddistributiontype12 - the type of the distribution for the download. the types are described at downloaddistributiontype1.
• POST Arguments: downloadbuy12 - is this download free or paid. 0 - free, 1 - paid.
• POST Arguments: downloadbuyreason12 - the description why is content is not for free.
• POST Arguments: downloadbuyprice12 - the price of this content in USD.
• POST Arguments: downloadgpgfingerprint12 - the gpg fingerprint of this download
• POST Arguments: downloadgpgsignature12 - the gpg signature of this download
• POST Arguments: downloadpackagename12 - the name of the package in the repository
• POST Arguments: downloadpackagerepository12 - the repository where the package is located
• POST Arguments: description - a description text of the entry
• POST Arguments: summary - a short summary of the entry
• POST Arguments: licensetype - the license this content is under. get the possible values by calling /v1/content/licenses
• POST Arguments: license - the license text
• POST Arguments: feedbackurl - a link to the page where users can post feedback
• POST Arguments: homepage - a link to the homepage of the entry
• POST Arguments: homepagetype - the type of the link. get the possible values by calling /v1/content/homepages
• POST Arguments: homepage2 - a link to the homepage of the entry
• POST Arguments: homepagetype2 - the type of the link.
• POST Arguments: homepage3 - a link to the homepage of the entry
• POST Arguments: homepagetype3 - the type of the link.
• POST Arguments: homepage4 - a link to the homepage of the entry
• POST Arguments: homepagetype4 - the type of the link.
• POST Arguments: homepage5 - a link to the homepage of the entry
• POST Arguments: homepagetype5 - the type of the link.
• POST Arguments: homepage6 - a link to the homepage of the entry
• POST Arguments: homepagetype6 - the type of the link.
• POST Arguments: homepage7 - a link to the homepage of the entry
• POST Arguments: homepagetype7 - the type of the link.
• POST Arguments: homepage8 - a link to the homepage of the entry
• POST Arguments: homepagetype8 - the type of the link.
• POST Arguments: homepage9 - a link to the homepage of the entry
• POST Arguments: homepagetype9 - the type of the link.
• POST Arguments: homepage10 - a link to the homepage of the entry
• POST Arguments: homepagetype10 - the type of the link.
• POST Arguments: video1 - a link to the video file
• POST Arguments: video2 - a link to the video file
• POST Arguments: video3 - a link to the video file
• POST Arguments: version - the version of this entry
• POST Arguments: changelog - the changelog of this entry
• POST Arguments: donation - do you want donation for this entry? possible values are "yes" or "" for no donation.
• POST Arguments: donationreason - a reason we you want a donation
• POST Arguments: osbsproject - the opensuse build service project id
• POST Arguments: osbspackage - the opensuse build service package id
• POST Arguments: announceupdate - announce this edit on the frontpage. possible values are 1 - announce, 0 - not announce, the default is 1
• Result: status xml
• Mandatory fields: "name" and "type" are mandatory fields
• Statuscodes: * 100 - successful * 101 - please specify all mandatory fields * 102 - no permission to change content
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/edit/12345 
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete content entry

Delete a content entry:

POST v1/content/delete/:contentid

• Arguments: contentid - Id of a content
• Result: status xml
• Statuscodes: * 100 - successful * 101 - no permission to change content
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/delete/12345
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

upload new download file

Upload a new download file to a content:

POST v1/content/uploaddownload/:contentid

• Arguments: contentid - Id of a content
• POST Arguments: localfile - The file to upload
• Result: status xml
• Statuscodes: * 100 - successful * 101 - upload error * 102 - localfile not found * 103 - no permission to change content
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/uploaddownload/12345
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete download file

Delete the download file from a content:

POST v1/content/deletedownload/:contentid

• Arguments: contentid - Id of a content
• Result: status xml
• Statuscodes: * 100 - successful * 101 - no permission to change content
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/deletedownload/12345
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

upload preview image

Upload a new preview image for a content:

POST v1/content/uploadpreview/:contentid/:previewid

• Arguments: contentid - Id of a content
• Arguments: previewid - Id of the preview image. (1,2 or 3)
• POST Arguments: localfile - The imagefile to upload
• Result: status xml
• Statuscodes: * 100 - successful * 101 - localfile not found * 102 - no permission to change content * 103 - preview must be 1, 2 or 3
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/uploadpreview/12345/1
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete preview image

Delete a preview image from a content:

POST v1/content/deletepreview/:contentid/:previewid

• Arguments: contentid - Id of a content
• Arguments: previewid - Id of the preview image. (1,2 or 3)
• Result: status xml
• Statuscodes: * 100 - successful * 101 - no permission to change content * 102 - preview not found
• Example:

$ curl -X POST http://api.opendesktop.org/v1/content/deletepreview/12345/1
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

getrecommendation

Gets a list of cross selling for a contentid

GET /v1/content/recommendations/:contentid

• URL Arguments: contentid - ID of an entry where you want to get similar or other recommended entries for.
• URL Arguments: page - The content page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ...
• URL Arguments: pagesize - The amount of entries per page.
• Result: content xml
• Statuscodes: * 100 - successful * 200 - too many API requests in the last 15 minutes from your IP address. please try again later.
• Example - get the second page of the list of recommendations for the content 123 from categories 1,2,3 and 4.

$ curl http://frank:password@api.opendesktop.org/v1/content/recommendations/123/?categories=1x2x3x4&page=1
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <content details="basic">
   <id>1422</id>
  </content>
  <content details="basic">
   <id>1223344</id>
  </content>
 </data>
</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.

/v1/fan/data/"contentid" 
* HTTP Method: GET 
* URL Arguments: contentid - Id of the content entry where you want to get the fans is from. 
* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... 
* URL Arguments: pagesize - The amount of entries per page. 
* Result: fan xml 
* Statuscodes: 
      * 100 - successful 
* Example - get the second page of the list of fans of the content with the id 123. The pagesize is 10
```xml
$ curl http://frank:password@api.opendesktop.org/v1/fan/data/123&page=1&pagesize=10
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>2</totalitems>
  <itemsperpage>10</itemsperpage>
 </meta>
 <data>
  <person details="fans">
   <personid>Frank</personid>
   <timestamp>2009-08-18T10:40:09+02:00</timestamp>
  </person>
  <person details="fans">
   <personid>Test</personid>
   <timestamp>2009-07-18T11:41:15+02:00</timestamp>
  </person>
 </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.

/v1/fan/status/"contentid" 
* HTTP Method: GET 
* URL Arguments: contentid - Id of the content entry where you want to get the fan status from. 
* Result: fan xml Possible stati are "fan" or "notfan" 
* Statuscodes: 
      * 100 - successful 
* Example - check if the user frank is a fan of the content 123
```xml
$ curl http://frank:password@api.opendesktop.org/v1/fan/status/123
<?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.

/v1/fan/add/"contentid" 
* HTTP Method: POST 
* URL Arguments: contentid - Id of the content entry 
* Result: fan xml 
* Statuscodes: 
      * 100 - successful 
* Example - the user frank becomes a fan of the content 123
```xml
$ curl -X POST http://frank:password@api.opendesktop.org/v1/fan/add/123
<?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.

/v1/fan/remove/"contentid" 
* HTTP Method: POST 
* URL Arguments: contentid - Id of the content entry 
* Result: fan xml 
* Statuscodes: 
      * 100 - successful 
* Example - the user frank is no longer a fan of the content 123
```xml
$ curl -X POST http://frank:password@api.opendesktop.org/v1/fan/remove/123
<?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.

/v1/knowledgebase/data/ 
* HTTP Method: GET 
* URL Arguments: content - Id of the content entry if you want to get knowledgebase entries from a specific content entry. 
* URL Arguments: type - Id of the category type. 
* URL Arguments: search - a keyword you want find in the name, description or answer of a knowledgebase entry. 
* URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest first or "alpha" - alphabetical 
* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... 
* URL Arguments: pagesize - The amount of entries per page. 
* Result: knowledgebase xml 
* Statuscodes: 
      * 100 - successful 
* Example - get the second page of the list of the newest knowledgebase entries from content 123 with the string foo in the name, description or answer:
```xml
$ curl http://frank:password@api.opendesktop.org/v1/knowledgebase/data?content=123&search=foo&sortmode=new&page=1
<?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.

/v1/knowledgebase/data/"contentid"/ 
* HTTP Method: GET 
* Arguments: knowledgebaseid - Id of a knowledgebase entry 
* Result: knowledgebase xml 
* Statuscodes: 
      * 100 - successful 
      * 101 - entry not found 
* Example:
```xml
$ curl http://frank:password@api.opendesktop.org/v1/knowledgebase/data/12345
<?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>

add

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

/v1/knowledgebase/data/ 
* HTTP Method: POST 
* POST Argument: subject - Subject of the new knowledgebase item 
* POST Argument: message - Content of the new knowledgebase item 
* POST Argument: content - id of the content entry to be added to if available 
* POST Argument: category - Id of the category to be added to if available. 
* Result: knowledgebase xml 
* Statuscodes: 
      * 100 - successful 
      * 101 - please specify all mandatory fields 
* Example:
```xml
$ curl -X POST http://frank:password@api.opendesktop.org/v1/knowledgebase/data
<?xml version="1.0"?>
<ocs>
<meta>
 <status>ok</status>
 <statuscode>100</statuscode>
 <message></message>
</meta>
</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.

/v1/event/data/ 
* HTTP Method: GET 
* URL Arguments: type - Id of the event type. 
* URL Arguments: country - ISO code of the country. 
* URL Arguments: startat - Earliest possible start date of the events. 
* URL Arguments: search - a keyword you want find in the name or description of a event entry. 
* URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest upcoming events first or "alpha" - alphabetical 
* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... 
* URL Arguments: pagesize - The amount of entries per page. 
* type 10: Party 
* type 15: User Group 
* type 20: Conference 
* type 25: Developer Meeting 
* type 50: Install Party 
* type 1000: otherParty 
* Result: event xml 
* Statuscodes: 
      * 100 - successful 
* Example - get the second page of the list of the newest events of 2009 from type party in the US with the string foo in the name or description:
```xml
$ curl http://frank:password@api.opendesktop.org/v1/event/data?country=us&startat=01-01-2009&type=10&search=foo&sortmode=new&page=1
<?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.

/v1/event/data/"eventid"/ 
* HTTP Method: GET 
* Arguments: eventid - Id of a event entry 
* Result: event xml 
* Statuscodes: 
      * 100 - successful 
      * 101 - entry not found 
* Example:
```xml
$ curl http://frank:password@api.opendesktop.org/v1/event/data/12345
<?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. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

v1/event/add 
* HTTP Method: POST 
* POST Arguments: name - the name of the entry 
* POST Arguments: category - the category of the event. possible values are: 
* 10 - Party 
* 15 - User Group 
* 20 - Conference 
* 25 - Developer Meeting 
* 50 - Install Party 
* 1000 - other 
* POST Arguments: description - the description text of the event. 
* POST Arguments: startdate - the startdate of the event. 
* POST Arguments: enddate - the enddate of the event 
* POST Arguments: organizer - the organizer of the event. 
* POST Arguments: location - the location where the event takes place. 
* POST Arguments: city - the city. 
* POST Arguments: country - the 2 letter iso code of the country. 
* POST Arguments: longitude - the longitude of the event. 
* POST Arguments: latitude - the latitude of the event. 
* POST Arguments: homepage - the homepage of the event. 
* POST Arguments: tel - the telefon number. 
* POST Arguments: fax - the fax number. 
* POST Arguments: email - a contact email address. 
* Result: status xml 
* Mandatory fields: "name" and "category" are mandatory fields 
* Statuscodes: 
      * 100 - successful 
      * 101 - please specify all mandatory fields 
      * 102 - no permission to add event 
* Example:
```xml
$ curl -X POST http://api.opendesktop.org/v1/event/add
<?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. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

v1/event/edit/"12345" 
* HTTP Method: POST 
* POST Arguments: name - the name of the entry 
* POST Arguments: category - the category of the event. possible values are: 
* 10 - Party 
* 15 - User Group 
* 20 - Conference 
* 25 - Developer Meeting 
* 50 - Install Party 
* 1000 - other 
* POST Arguments: description - the description text of the event. 
* POST Arguments: startdate - the startdate of the event. 
* POST Arguments: enddate - the enddate of the event 
* POST Arguments: organizer - the organizer of the event. 
* POST Arguments: location - the location where the event takes place. 
* POST Arguments: city - the city. 
* POST Arguments: country - the 2 letter iso code of the country. 
* POST Arguments: longitude - the longitude of the event. 
* POST Arguments: latitude - the latitude of the event. 
* POST Arguments: homepage - the homepage of the event. 
* POST Arguments: tel - the telefon number. 
* POST Arguments: fax - the fax number. 
* POST Arguments: email - a contact email address. 
* Result: status xml 
* Mandatory fields: "name" and "category" are mandatory fields 
* Statuscodes: 
      * 100 - successful 
      * 101 - please specify all mandatory fields 
      * 102 - no permission to change event 
* Example: http://api.opendesktop.org/v1/event/edit/12345
```xml
$ curl -X POST http://api.opendesktop.org/v1/event/edit/12345
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

delete event entry

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

v1/event/delete/"contentid" 
* HTTP Method: POST 
* Arguments: eventid - Id of a event 
* Result: status xml 
* Statuscodes: 
      * 100 - successful 
      * 101 - no permission to change event 
* Example:
```xml
$ curl -X POST http://api.opendesktop.org/v1/event/delete/12345
<?xml version="1.0"?>
<ocs>
 <status>ok</status>
 <message></message>
</ocs>

COMMENTS

get

Gets a list of comments.

/v1/comments/data/"type"/"contentid"/"contentid2" 
* HTTP Method: GET 
* URL Arguments: type - Id of the content entry where you want to get the comments is from. 
* URL Arguments: contentid - Id of the content entry where you want to get the comments is from. 
* URL Arguments: contentid2 - Id of the content entry where you want to get the comments is from. 
* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... 
* URL Arguments: pagesize - The amount of entries per page. 
* Result: comments xml 
* Statuscodes: 
      * 100 - successful 
* Types: 
      * 1 - content 
      * 4 - forum 
      * 7 - knowledgebase 
      * 8 - event 
* Example - get the second page of the list of comments of the content with the id 123. The pagesize is 10
```xml
$ curl http://frank:password@api.opendesktop.org/v1/comments/data/1/123/0&page=1&pagesize=10
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <comment>
   <id>234</id>
   <subject>vfvvdsx</subject>
   <text>vdxvvsx</text>
   <childcount>0</childcount>
   <user>test</user>
   <date>2005-01-29T18:58:40+01:00</date>
   <score>50</score>
  </comment>
  <comment>
   <id>235</id>
   <subject>vxvdfvd</subject>
   <text>gfdgfdgfgfgf
   </text>
   <childcount>1</childcount>
   <user>test</user>
   <date>2005-01-29T19:17:06+01:00</date>
   <score>60</score>
   <children>
    <comment>
     <id>315</id>
     <subject>Re: jjjjjjjjjjjjjjj</subject>
     <text>gfdg</text>
     <childcount>0</childcount>
     <user>Frank</user>
     <date>2007-03-13T21:34:43+01:00</date>
     <score>40</score>
    </comment>
   </children>
  </comment>
 </data>
</ocs>

add

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

v1/comments/add 
* HTTP Method: POST 
* Arguments: type - type of comment 
* Arguments: content - the content id where the comment belongs 
* Arguments: content2 - the sub content id where the comment belongs 
* Arguments: parent - the id of the parent comment if the new comment is a reply 
* Arguments: subject - the subject of the comment 
* Arguments: message - the message text of the comment 
* Types: 
      * 1 - content 
      * 4 - forum 
      * 7 - knowledgebase 
      * 8 - event 
* Result: status xml 
* Statuscodes: 
      * 100 - successful 
      * 101 - content must not be empty 
      * 102 - message or subject must not be empty 
      * 103 - no permission to add a comment 
* Example:
```xml
$ curl -X POST http://api.opendesktop.org/v1/comments/add
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

vote

Vote for one specific comment. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/comments/vote/"commentsid" 
* HTTP Method: POST 
* Arguments: contentid - Id of a comment 
* POST Arguments: vote - The vote. An integer between 0 to 100. 0 equals bad and 100 equals good 
* Result: status xml 
* Statuscodes: 
      * 100 - successful 
      * 101 - comment not found 
      * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. 
* Example:
```xml
$ curl -X POST http://api.opendesktop.org/v1/content/vote/12345 -d "vote=4" 
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <comment>
   <id>1234567</id>
  </comment>
 </data>
</ocs>

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.

/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. 
* Statuscodes: 
      * 100 - successfull 
Example - get the value of the key language of the application parley from myself. Example: 
```xml
$ curl http://frank:password@api.opendesktop.org/v1/privatedata/getattribute/parley/language
<?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>
   <lastmodified>2007-11-01T22:45:20+01:00</lastmodified>
  </attribute>
 </data>
</ocs>

set attribute

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

/v1/privatedata/setattribute/"app"/"key" 
* HTTP method: POST 
* Arguments: app - The application where you want to store this attribute at. 
* Arguments: key - The key of the attribute. 
* POST arguments: value - The value of the attribute. 
* Statuscodes: 
      * 100 - successfull 
Example - set the value of the key "language" of the application "parley" to "italian". Example: 
```xml
$ curl -X POST http://frank:password@api.opendesktop.org/v1/privatedata/setattribute/parley/language -d "value=italian"
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

delete attribute

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

/v1/privatedata/deleteattribute/"app"/"key" 
* HTTP method: POST 
* Arguments: app - The application where the key is stored. 
* Arguments: key - The key of the attribute. 
* Statuscodes: 
      * 100 - successfull 
Example - delete the attribute with the key "language" and the application "parley": 
```xml
$ curl -X POST http://frank:password@api.opendesktop.org/v1/privatedata/deleteattribute/parley/language
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
</ocs>

FORUM

list

Gets a list of forums.

/v1/forum/list 
* HTTP Method: GET 
* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, 
* URL Arguments: pagesize - The amount of entries per page. 
* Result: comments xml 
* Statuscodes: 
      * 100 - successful 
Example  - get the second page of the list of forums. The pagesize is 10:
```xml
$ curl http://frank:password@api.opendesktop.org/v1/forums/data&page=1&pagesize=10
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message></message>
</meta>
<data>
<forum>
 <id>234</id>
 <name>vfvvdsx</name>
 <description>test</description>
 <date>2005-01-29T18:58:40+01:00</date>
 <icon>http://forum.example.org/images/forum-img.png</icon>
 <childcount>0</childcount>
 <children></children>
 <topics>123</topics>
</forum>
<forum>
 <id>876</id>
 <name>yheweq</name>
 <description>foobar</description>
 <date>2005-01-29T18:58:40+01:00</date>
 <icon>http://forum.example.org/img/forum-icon.gif</icon>
 <childcount>1</childcount>
 <children>
    <forum>
      <id>234</id>
      <name>cameras</name>
      <description>new forum</description>
      <date>2005-01-29T18:58:40+01:00</date>
      <icon>http://forum.example.org/images/icon.jpg</icon>
      <childcount>0</childcount>
      <children></children>
      <topics>5</topics>
    </forum>
 </children>
 <topics>789</topics>
</forum>
</data>
</ocs>

topics/list

Gets a list of a specific set of topics.

/v1/forum/topics/list 
* HTTP Method: GET 
* URL Arguments: forum - Id of the forum you are requesting a list of. Not required if a search term is provided. 
* URL Arguments: search - a keyword you want find in the name, 
* URL Arguments: description or comment of a topic. Not required if a forum id is provided. 
* URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest first or "alpha" - alphabetical 
* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, 
* URL Arguments: pagesize - The amount of entries per page. 
* Result: forum topic listing xml 
* Statuscodes: 
      * 100 - successful 
Example - get the second page of the list of the newest topics from forum 123 with the string foo in the subject, content or the comment. Additional forums can be specified to be searched by adding further &forum[]= entries to the request.
```xml
$ curl http://frank:password@api.opendesktop.org/v1/forum/topics/list?forum[]=123&search=foo&sortmode=new&page=1
<?xml version="1.0"?>
<ocs>
<meta>
 <status>ok</status>
 <statuscode>100</statuscode>
 <message></message>
 <totalitems>2</totalitems>
 <itemsperpage>10</itemsperpage>
</meta>
<data>
 <topic details="detail">
  <id>1</id>
  <forumid>123</forumid>
  <user>testy</user>
  <changed>2009-02-07T23:14:11+01:00</changed>
  <subject>Random forum post</subject>
  <content>Just testing</content>
  <comments>0</comments>
 </topic>
</data>

forum/topics/add

Add a new topic to a forum. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. All arguments are mandatory.

/v1/forum/topic/add 
* HTTP Method: POST 
* POST Argument: subject - Subject of the new topic 
* POST Argument: content - Content of the first post of the new topic 
* POST Argument: forum - id of the forum entry to be added to if available 
* Result: ocs xml 
* Statuscodes: 
      * 100 - successful 
      * 101 - please specify all mandatory fields 
Example:
```xml
$ curl -X POST http://frank:password@api.opendesktop.org/v1/forum/topic/add
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message></message>
</meta>
</ocs>

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.

• Syntax: /v1/buildservice/project/create
• HTTP method: POST
• Result: project id
• POST Argument: name - string, the project's human readable name
• POST Argument: version - string, the version string for this project
• POST Argument: license - string, with suggestions from the license list (see content/licenses)
• POST Argument: url - url, a web address for the project
• POST Argument: developers - string, a newline separated list of developers on the project. Should be in the form of "Developer Name email@address"
• POST Argument: summary - string, a short, one line description of the project. Note: no newlines accepted (if newlines are passed, they will be stripped out)
• POST Argument: description - string, a long description of the project
• POST Argument: requirements - string, describes the required packages for the project, if applicable
• POST Argument: specfile - string, the contents of the spec file
• Mandatory fields: name
• Result: * projectid (int)
• Statuscodes: * 100 - success * 101 - required argument missing: name * 110 - url was not an acceptable format * 111 - developers was not in an acceptable format * 112 - summary contained newlines Example - create a new project xith two developers:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/project/create -d "name=A Project" -d "developers[0][name]=Frank Karlitschek" -d "developers[0][url]=[karlitschek@kde.org" -d "developers[1][name]=Dan jensen" -d "developers[1][url]=[admin@leinir.dk]"
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <projectid>122</projectid>
  </data>
</ocs>

get

Get all information for a specified project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

• Syntax: /v1/buildservice/project/get/"project"
• HTTP method: GET
• URL argument: project - the projectid of the project for which information should be fetched
• Mandatory fields: "project"
• Result: project xml - see buildservice/project/create for data types
• Statuscodes: * 100 - success * 101 - no such project * 102 - project id should be an integer Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/project/get/122
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <project>
      <projectid>122</projectid>
      <name>A Project</name>
      <version>1.0pre1</version>
      <license>Creative Commons Attribution Share-Alike 2.0</license>
      <url>http://somesite.com/</url>
      <developers>Frank Karlitschek &lt;karlitschek@kde.org&gt;
Dan Jensen &lt;admin@leinir.dk&gt;</developers>
      <summary>A neat little project which does something</summary>
      <description>A long description of the project
      
which even cleverly includes multiple lines</description>
      <requirements></requirements>
      <specfile>#
# spec file for package a-project
#
# Copyright (C) 2010 Frank Karlitschek (mailto:karlitschek@kde.org)
# Copyright (C) 2010 Dan Jensen (mailto:admin@leinir.dk)
#

Name: a-project
Summary: A neat little project which does something

Version: 1.0pre1
Release: 0
License: Creative Commons Attribution Share-Alike 2.0
Url: http://somesite.com/
BuildRoot: /var/tmp/%name-root
Source: a-project-1.0pre1.tar.bz2

%description
A long description of the project
      
which even cleverly includes multiple lines

(etc etc...)</specfile>
    </project>
  </data>
</ocs>

delete

Delete a specific project and the uploaded source files. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

• Syntax: /v1/buildservice/project/delete/"project"
• HTTP method: POST
• URL argument: project - projectid, the id of the project to be deleted
• Statuscodes: * 100 - success * 101 - no such project * 102 - project id should be an integer * 110 - project delete failed (details in meta message) Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/project/delete/122
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

edit

Set any of the values found on a project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

• Syntax: /v1/buildservice/project/edit/"project"
• HTTP method: POST
• URL argument: project - projectid, the id of the project to change details on
• POST Argument: name - string, the project's human readable name
• POST Argument: version - string, the version string for this project
• POST Argument: license - string, with suggestions from the license list (see content/licenses)
• POST Argument: url - url, a web address for the project
• POST Argument: developers - string, a newline separated list of developers on the project. Should be in the form of "Developer Name email@address"
• POST Argument: summary - string, a short, one line description of the project. Note: no newlines accepted (if newlines are passed, they will be stripped out)
• POST Argument: description - string, a long description of the project
• POST Argument: requirements - string, describes the required packages for the project, if applicable
• POST Argument: specfile - string, the contents of the spec file
• Mandatory fields: "project"
• Statuscodes: * 100 - success * 101 - no such project * 102 - projectid no an int * 110 - url was not an acceptable format * 111 - developers was not in an acceptable format Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/project/edit/122 -d "name=A Project" -d "summary=A neat little project which does something" 
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

list

List all projects for the currently authorized user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

• Syntax: /v1/buildservice/project/list
• 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: projectlist xml
• HTTP method: GET
• Statuscodes: * 100 - success Example - when the user has exactly one project:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/project/list
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <projectlist>
      <project>
        <projectid>122</projectid>
        <name>A Project</name>
        <version>1.0pre1</version>
        <license>Creative Commons Attribution Share-Alike 2.0</license>
        <url>http://somesite.com/</url>
        <developers>Frank Karlitschek &lt;karlitschek@kde.org&gt;
Dan Jensen &lt;admin@leinir.dk&gt;</developers>
        <summary>A neat little project which does something</summary>
        <description>A long description of the project
      
which even cleverly includes multiple lines</description>
        <requirements></requirements>
        <specfile></specfile>
      </project>
    </projectlist>
  </data>
</ocs>

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
• POST argument: localfile - The source bundle to upload
• Mandatory fields: "project", "localfile"
• Result: specfile - string, the contents of generated specfile
• Statuscodes: * 100 - success * 101 - no such project * 102 - project id should be an int * 103 - source bundle file not correctly uploaded * 104 - source bundle was an unrecognised format Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/project/uploadsource/122
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

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
• Statuscodes: * 100 - success Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/list
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <remoteaccountslist>
      <remoteaccount>
        <id>2</id>
        <type>1</type>
        <typeid>mbs</typeid>
        <data></data>
        <login>frank</login>
        <password>password</password>
      </remoteaccount>
      <remoteaccount>
        <id>7</id>
        <type>2</type>
        <typeid>1</typeid>
        <data></data>
        <login>frank</login>
        <password>password</password>
      </remoteaccount>
    </remoteaccountslist>
  </data>
</ocs>

add

Add a new remote account reference to a user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

• Syntax: /v1/buildservice/remoteaccounts/add
• HTTP method: POST
• POST argument: type - int, which type of account we're dealing with (1 is buildservice, 2 is publisher)
• POST argument: typeid - string, the ID of the remote service the account is with
• 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
• Mantadory fields: type, typeid
• Result: remoteaccountid
• Statuscodes: * 100 - success * 101 - no such service * 102 - service id was not recognised Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/add -d "type=1" -d "typeid=mbs" 
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <remoteaccountid>7</remoteaccountid>
  </data>
</ocs>

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
• Mantadory fields: remoteaccountid
• Result: remoteaccountid
• Statuscodes: * 100 - success * 101 - no such remote account Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/edit/7 -d "login=frank" -d "password=bet123ter" 
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

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
• Statuscodes: * 100 - success * 101 - no such remote account Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/get/7
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <remoteaccount>
        <id>7</id>
        <type>2</type>
        <typeid>1</typeid>
        <data></data>
        <login>frank</login>
        <password>bet123ter</password>
    </remoteaccount>
  </data>
</ocs>

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.

• Syntax: /v1/buildservice/remoteaccounts/remove/remoteaccountid
• HTTP method: POST
• Statuscodes: * 100 - success * 101 - no such remote account Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/remove/7
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

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
• Statuscodes: * 100 - success Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/buildservices/list
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildservices>
      <buildservice>
        <id>1</id>
        <name>Some Build Service</name>
        <registrationurl>http://bs.some.com/user/new</registrationurl>
        <supportedtargets>
          <target>
            <id>1</id>
            <name>i386</name>
          </target>
          <target>
            <id>2</id>
            <name>x86_64</name>
          </target>
          <target>
            <id>3</id>
            <name>armv5</name>
          </target>
        </supportedtargets>
      </buildservice>
    </buildservices>
  </data>
</ocs>

get

Get a the information on a particular build service.

• Syntax: /v1/buildservice/buildservices/get/"buildserviceid"
• HTTP method: GET
• URL argument: buildserviceid - the ID of the build service
• Mandatory fields: "buildserviceid"
• 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
• Statuscodes: * 100 - success * 101 - no such build service Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/buildservices/get/1
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildservice>
      <id>1</id>
      <name>Some Build Service</name>
      <registrationurl>http://bs.some.com/user/new</registrationurl>
      <supportedtargets>
        <target>
          <id>1</id>
          <name>i386</name>
        </target>
        <target>
          <id>2</id>
          <name>x86_64</name>
        </target>
        <target>
          <id>3</id>
          <name>armv5</name>
        </target>
      </supportedtargets>
    </buildservice>
  </data>
</ocs>

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, ...
• URL argument: pagesize - The amount of entries your get per page.
• Mandatory fields: none
• Result: buildjoblist xml - a list of build job data
• Statuscodes: * 100 - success * 101 - no such project * 102 - project id should be an int Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/jobs/list/122
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildjobs>
      <buildjob>
        <id>12</id>
        <project>122</project>
        <buildservice>mbs</buildservice>
        <target>2</target>
        <name>armv5 job 12</name>
        <status>1</status>
        <progress>0.56</progress>
        <url>http://bs.some.com/job/54322</url>
        <message></message>
      </buildjob>
      <buildjob>
        <id>18</id>
        <project>122</project>
        <buildservice>obs</buildservice>
        <target>4</target>
        <name>armv5 job 14</name>
        <status>1</status>
        <progress>0.88</progress>
        <url>http://bs.some.com/job/54324</url>
        <message></message>
      </buildjob>
    </buildjobs>
  </data>
</ocs>

create

Create a new build job. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

• Syntax: /v1/buildservice/jobs/create/"project"/"buildservice"/"target"
• HTTP method: POST
• URL argument: project - projectid, the id of the project to create a new build job for
• URL argument: buildservice - buildserviceid, the id of the build service to create a new job for
• URL argument: target - string, the target of this job. Must be supported by the build service
• Mandatory fields: "project", "buildservice", "target"
• Result: id - int, aka buildjobid, the id of the newly created build job
• Statuscodes: * 100 - success * 101 - no such project * 102 - project id should be an integer * 103 - no such build service * 104 - build service id should be an integer * 105 - build service does not support target * 106 - failed to create build job (further information in meta message) Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/jobs/create/122/1/armv5
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildjobid>616</buildjobid>
  </data>
</ocs>

cancel

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

• Syntax: /v1/buildservice/jobs/cancel/"buildjob"
• HTTP method: POST
• URL argument: buildjob - buildjobid, the id of the build which should be cancelled
• Mandatory fields: "buildjob"
• Statuscodes: * 100 - success * 101 - no such build job * 102 - build job id should be an integer * 103 - job not running * 104 - failed (further information in meta message) Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/jobs/cancel/616
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

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
• Statuscodes: * 100 - success * 101 - no such build job * 102 - build job id should be an integer Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/jobs/get/616
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildjob>
      <id>12</id>
      <project>122</project>
      <buildservice>mbs</buildservice>
      <target>2</target>
      <name>armv5 job 12</name>
      <status>1</status>
      <progress>0.56</progress>
      <url>http://bs.some.com/job/54322</url>
      <message></message>
    </buildjob>
  </data>
</ocs>

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.
• Statuscodes: * 100 - success * 101 - no such build job * 102 - build job id should be an integer Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/jobs/getoutput/616
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <output>-- Found GCC: /usr/bin/gcc
-- Found X11: /usr/lib64/libX11.so
(etc etc)
    </output>
  </data>
</ocs>

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
• Statuscodes: * 100 - success * 101 - no such user * 102 - user has not registered with any publishers Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/publishing/getpublishingcapabilities
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <publishers>
      <publisher>
        <id>1</id>
        <name>Some App Store</name>
        <registrationurl>http://store.some.com/user/new</registrationurl>
        <fields>
          <field>
            <name>Name</name>
            <fieldtype>string</fieldtype>
            <options></options>
            <fieldsize>256</fieldsize>
            <required>true</required>
          </field>
          <field>
            <name>Description</name>
            <fieldtype>longtext</fieldtype>
            <options></options>
            <fieldsize>4294967296</fieldsize>
            <required>false</required>
          </field>
          <field>
            <name>Category</name>
            <fieldtype>item</fieldtype>
            <options>
              <option>Game</option>
              <option>Productivity</option>
              <option>Gadget</option>
            </options>
            <fieldsize>0</fieldsize>
            <required>true</required>
          </field>
        </fields>
        <supportedtargets>
          <target>i386</target>
          <target>x86_64</target>
          <target>armv5</target>
        </supportedtargets>
      </publisher>
      <publisher>
        <id>2</id>
        <name>Somewhere</name>
        <registrationurl>http://store.some.where/register</registrationurl>
        <fields></fields>
        <supportedtargets>
          <target>i386</target>
        </supportedtargets>
      </publisher>
    </publishers>
  </data>
</ocs>

getpublisher

Get the descriptive information about a publisher.

• Syntax: /v1/buildservice/publishing/getpublisher/"publisher"
• HTTP method: GET
• 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
• Statuscodes: * 100 - success * 101 - no such publisher * 102 - publisher id should be an integer Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/publishing/getpublisher/5
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <publisher>
      <id>1</id>
      <name>Some App Store</name>
      <registrationurl>http://store.some.com/user/new</registrationurl>
      <fields>
        <field>
          <name>Name</name>
          <fieldtype>string</fieldtype>
          <options></options>
          <fieldsize>256</fieldsize>
          <required>true</required>
        </field>
        <field>
          <name>Description</name>
          <fieldtype>longtext</fieldtype>
          <options></options>
          <fieldsize>4294967296</fieldsize>
          <required>false</required>
        </field>
        <field>
          <name>Category</name>
          <fieldtype>item</fieldtype>
          <options>
            <option>Game</option>
            <option>Productivity</option>
            <option>Gadget</option>
          </options>
          <fieldsize>0</fieldsize>
          <required>true</required>
        </field>
      </fields>
      <supportedtargets>
        <target>i386</target>
        <target>x86_64</target>
        <target>armv5</target>
      </supportedtargets>
    </publisher>
  </data>
</ocs>

publishtargetresult

Publish the result of a specific build job to one publisher. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

• Syntax: /v1/buildservice/publishing/publishtargetresult/"buildjob"/"publisher"
• HTTP method: POST
• URL argument: buildjob - buildjobid, the id of the build job which the result should be published
• URL argument: publisher - publisherid, the id of the publisher to publish a result to
• Mandatory fields: "buildjob", "publisher"
• Statuscodes: * 100 - success * 103 - no such build job * 104 - build job not completed * 105 - build job id should be an integer * 106 - no such publisher * 107 - publisher id should be an integer * 108 - publishing failed (further information in meta message) Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/publishing/publishtargetresult/616/5 
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
</ocs>

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
• Mandatory fields: project, fields
• Statuscodes: * 100 - success * 101 - no such project * 102 - project id should be an integer * 103 - field data not correct (further information in meta message) * 104 - field data missing (further information in meta message) Example:

$ curl -X POST http://frank:password@api.opendesktop.org/v1/buildservice/publishing/savefields/122 -d "fields[0]['name']=Name" -d "fields[0]['fieldtype']="string" -d "fields[0]['data']=A Project" -d "fields[1]['name']=Category" -d "fields[1]['fieldtype']=item" -d "fields[1]['data']=Nifty" 
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>failed</status>
    <statuscode>103</statuscode>
    <message>The item "Nifty" does not exist in the list of possible options. The options are: "Game", "Productivity", "Gadget"</message>
  </meta>
</ocs>

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
• Statuscodes: * 100 - success * 101 - no such project * 102 - project id should be an integer Example:

$ curl http://frank:password@api.opendesktop.org/v1/buildservice/publishing/getfields/122
<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <fields>
      <field>
        <name>Name</name>
        <fieldtype>string</fieldtype>
        <data>A Project</data>
      </field>
      <field>
        <name>Summary</name>
        <fieldtype>string</fieldtype>
        <data>A neat little project which does something</data>
      </field>
      <field>
        <name>Category</name>
        <fieldtype>item</fieldtype>
        <data>Gadget</data>
      </field>
    </fields>
  </data>
</ocs>

CLOUD

system / webapps

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

/v1/cloud/system/webapps 
* HTTP method: GET 
* Statuscodes: 
      * 100 - successfull 
Example - get the list of available webapps:
```xml
$ curl http://frank:password@myowncloud.org/ocs/v1.php/cloud/system/webapps
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <cloud>
   <name>Files</name>
   <url>http://localhost/owncloud/apps/files/</url>
   <icon></icon>
  </cloud>
  <cloud>
   <name>Media</name>
   <url>http://localhost/owncloud/apps/media/</url>
   <icon></icon>
  </cloud>
  <cloud>
   <name>Contacts</name>
   <url>http://localhost/owncloud/apps/contacts/</url>
   <icon></icon>
  </cloud>
  <cloud>
   <name>Pictures</name>
   <url>http://localhost/owncloud/apps/gallery/</url>
   <icon></icon>
  </cloud>
 </data>
</ocs>

user / get quota

Reads the quota and the currently used space for a user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/user/"user"/quota 
* HTTP method: GET 
* Statuscodes: 
      * 100 - successfull 
Example - gat the quota and the currently used space for myself: 
```xml
$ curl http://frank:password@myowncloud.org/ocs/v1.php/cloud/user/frank/quota
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
  <totalitems>1</totalitems>
 </meta>
 <data>
  <quota>6466643608</quota>
  <free>6460997632</free>
  <used>5645976</used>
  <relative>0.09</relative>
 </data>
</ocs>

user / set quota

Sets the quota for a user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/user/"user"/quota 
* HTTP method: POST 
* Statuscodes: 
      * 100 - successfull 
Example - sets the quota for and the currently user frank to 1234. Example: 
```xml
$ curl -X POST http://frank:password@myowncloud.org/ocs/v1.php/cloud/user/frank/quota -d quota=1234
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data/>
</ocs>

user / get public key

Reads all public key used to encrypt the given file. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/file/"file"/publickeys 
* HTTP method: GET 
* Statuscodes: 
      * 100 - successfull 
      * 404 - key does not exist 
      * 300 - encryption not enabled 
Example - get all public keys used to encrypt the file: 
```xml
$ curl http://frank:password@myowncloud.org/ocs/v1.php/cloud/file/path%2Fto%2Ffile.txt/publickeys
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <key1>publickeyfromuser1</key1>
  <key2>publickeyfromuser2</key2>
  ...
  <keyN>publickeyfromuserN</keyN>
 </data>
</ocs>

user / get private key

Reads the private key of the user. Only authenticated users are allowed to access this method and the user will always get access to his private key only. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/privatekey 
* HTTP method: GET 
* Statuscodes: 
      * 100 - successfull 
      * 404 - key does not exist 
      * 300 - encryption not enabled 
Example - get the private key for a user: 
```xml
$ curl http://frank:password@myowncloud.org/ocs/v1.php/cloud/privatekey
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <key>treThisistheprivatekeyoffrank654fhfghf</key>
 </data>
</ocs>

user / get file key

Reads the file encryption key of the file. Only authenticated users are allowed to access this method and the user will always get access to his private key only. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/file/"file"/filekey 
* HTTP method: GET 
* Statuscodes: 
      * 100 - successfull 
      * 404 - key does not exist 
      * 300 - encryption not enabled 
Example - get the encryption key of a file: 
```xml
$ curl http://frank:password@myowncloud.org/ocs/v1.php/cloud/file/path%2Fto%2Ffile.txt/filekey
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data>
  <key>encryptionkeyforgivenfile</key>
 </data>
</ocs>

user / set public key

Writes public key of the user to the server. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/publickey 
* HTTP method: POST TODO PUT? Why
* Statuscodes: 
      * 100 - successfull 
      * 404 - could not write public key to server 
      * 300 - encryption not enabled 
Example - write public key to the server:
```xml
$ curl -X POST http://frank:password@myowncloud.org/ocs/v1.php/cloud/publickey -d "key=publickeyoftheuser"
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data/>
</ocs>

user / set private key

Writes private key of the user to the server. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/privatekey 
* HTTP method: POST 
* Statuscodes: 
      * 100 - successfull 
      * 404 - could not write private key to server 
      * 300 - encryption not enabled 
Example - write private key to the server: 
```xml
$ curl -X POST http://frank:password@myowncloud.org/ocs/v1.php/cloud/privatekey -d "key=privatekeyoftheuser" 
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data/>
</ocs>

user / set file key

Writes file encryption key of the file to the server. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/filekey
* FIXME make file a path param
* HTTP method: POST 
* Statuscodes: 
      * 100 - successful  
      * 404 - could not write file key to server 
      * 300 - encryption not enabled 
Example - write file encryption key to the server: 
```xml
$ curl -X POST http://frank:password@myowncloud.org/ocs/v1.php/cloud/filekey -d "key=filekeyofthefile" -d "file=file/to/which/the/key/belongs"
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data/>
</ocs>

users / adduser

Create a new user on the cloud server. Only authenticated administrator users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header.

/v1/cloud/users 
* HTTP method: POST 
* POST argument: userid - string, the required username for the new user 
* POST argument: password - string, the required password for the new user 
* Statuscodes: 
      * 100 - successful 
      * 101 - invalid input data 
      * 102 - username already in user 
      * 103 - unknown error occurred whilst adding the user 
Example - creates the user 'Frank' with password 'frankspassword': 
```xml
$ curl -X POST http://frank:password@myowncloud.org/ocs/v1.php/cloud/users -d "user=Frank" -d "password=frankspassword"
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message></message>
 </meta>
 <data/>
</ocs>