# Open Collaboration Services v1.6 Frank Karlitschek [[MailTo(karlitschek AT kde.org)|MailTo(karlitschek AT kde.org)]] [[OCS Mailinglist|http://lists.freedesktop.org/mailman/listinfo/ocs]] [[!toc ]] ## 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 ## 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|https://frank:password@api.opendesktop.org/v1/activity?page=3]] #### example api key [[https://API5142830791365744186814934@api.opendesktop.org/v1/activity?page=3|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|Specifications/open-collaboration-services]] * [[PERSON|Specifications/open-collaboration-services]] * [[FRIEND|Specifications/open-collaboration-services]] * [[MESSAGE|Specifications/open-collaboration-services]] * [[ACTIVITY|Specifications/open-collaboration-services]] * [[CONTENT|Specifications/open-collaboration-services]] * [[FAN|Specifications/open-collaboration-services]] * [[KNOWLEDGEBASE|Specifications/open-collaboration-services]] * [[EVENT|Specifications/open-collaboration-services]] * [[COMMENTS|Specifications/open-collaboration-services]] * [[PRIVATE DATA|Specifications/open-collaboration-services]] * [[FORUM|Specifications/open-collaboration-services]] * ...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: opendesktop https://api.opendesktop.org/v1/ openDesktop.org https://opendesktop.org/terms/ https://opendesktop.org/usermanager/new.php testy http://api.foo.org Foo provider https://foo.org/terms/ https://foo.org/register.php The KDE provider file is here: [[http://download.kde.org/ocs/providers.xml|http://download.kde.org/ocs/providers.xml]] ## Service Specifications ### CONFIG #### config get some basic API configuration information * Syntax: /v1/config * Method: GET * Statuscodes: * 100 - successful Example: GET Example: ok 100 1.4 openDesktop.org api.openDesktop.org frank@openDesktop.org true ### 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. * Syntax: /v1/person/check * Method: POST * 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: POST postdata: login="frank" password="123456" Checks if frank,123456 is a valid account. Example: ok 100 frank #### add Registers a new user account on the server. The users still have to approve the account by clicking on a link in a confirmation email to activate the account. Only alphanumeric characters are allowed and the password has to be 8 characters or longer. * Syntax: /v1/person/add * Method: POST * POST Arguments: login - The login or the API key * POST Arguments: password - The password * POST Arguments: firstname - The firstname of the user * POST Arguments: lastname - The lastname of the user * POST Arguments: email - the email address. the address must be valid, because the user gets a confirmation email to this address. * 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: POST postdata: login="frank" password="123456" firstname="Frank" lastname="Karlitschek" email="[[karlitschek@kde.org|mailto:karlitschek@kde.org]]" registers a new user account. Example: ok 100 #### search find a specific list of persons. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. It is not possible to get a list of more than 1000 people because of privacy issues. * Syntax: /v1/person/data * HTTP method: GET * url arguments: name - A part of the name or personid you want to search for. * url arguments: country - The country id of the country you want to search in. * url arguments: city - The name of the city as a string. * url arguments: description - A string you want to search for in the description and other fields of the person. * url arguments: pc - A string you want to search for in the pc/hardware field of the person. * url arguments: software - A string you want to search for in the software field of the person. * url arguments: longitude - The longitude of the position where you want to find people. * url arguments: latitude - The latitude of the position where you want to find people. * url arguments: distance - The maximum distance of the person to you longitude/latitude position. if you specify the latitude and longitude but no distance the resultset will be ordered by distance. The unit of the distance parameter is degrees. * url arguments: attributeapp - The applicationname or namespace of the attribute. * url arguments: attributekey - The key of the attribute. * url arguments: attributevalue - The value of the attribute. * url arguments: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ... * url arguments: pagesize - The amount of entries your get per page. * Statuscodes: * 100 - successfull * 102 - more than 1000 people found. it is not allowed to fetch such a big resultset. please specify more search conditions * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. * Result: personlist xml Example: GET Gets the third page of the search result list from the search for person where "eter" is in the nickname, firstname or lastname and "don" is in the city and who is interested in "development" and who lived near latitude:11.2 and longitude:22.0 witch a tolerance of 0.5 Example: ok 100 2 10 Testy 0 public Peter - London peter 0 public Frank Test company male London #### 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. * Syntax: /v1/person/data/"personid"/ * HTTP method: GET * Arguments: personid - Id of a person. for example "frank" * Result: person xml * Statuscodes: * 100 - successfull * 101 - person not found * 102 - data is private * Example: GET Example: ok 100 Frank 1 visible only for registered users Frank Test male developer openDesktop.org www.facebook.com/foo Facebook http://openDesktop.org/img/socialicons/emblem-facebook.png opendesktop.org http://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg 1 http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg 1 1973-07-25 working Stuttgart Germany karli kde-dev, plasma irc://irc.freenode.org/kde-dev irc://irc.freenode.org/plasma lot of stuff nothing travel english php, c++ nin fightclub ut3 http://www.KDE-Look.org/usermanager/search.php?username=Frank #### get self get the data from yourself. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /v1/person/self * HTTP method: GET * Result: person xml * Statuscodes: * 100 - successfull * Example: GET Example: ok 100 Frank 1 visible only for registered users Frank Test male developer opendesktop.org opendesktop.org http://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg 1 http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg 1 1973-07-25 working Stuttgart Germany karli kde-dev, plasma irc://irc.freenode.org/kde-dev irc://irc.freenode.org/plasma lot of stuff nothing travel english php, c++ nin fightclub ut3 http://www.KDE-Look.org/usermanager/search.php?username=Frank #### edit Update the latitude, longitude, city and country of myself. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /v1/person/self * Method: POST * 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: POST postdata: longitude="1.23" latitude="3.45" Updated my position to 1.23 and 3.45 Example: ok 100 #### balance Get the account balance of a user. * Syntax: /v1/person/balance * HTTP Method: GET * Result: status xml * Example: Example: ok 100 USD 1.49 #### get attributes Gets the list of extended attributes of a person. You can store several attributes to you person record which are publicly readable for everybody. The attributes are key/value pairs with an "app" parameter as namespace. Store data which is only interesting for your application with your application name as a app namespace. If the data is of general interest use "global" as app parameter. The parameter "app" and "key" are optional in the url. So you access all the attributes from the person or only the attributes from a specific application or the only the value of one specific key. You can search for users which have specific attributes with the search method. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * syntax: /v1/person/attributes/"personid"/"app"/"key" * HTTP method: GET * Arguments: personid - The person from which you want to get the attributes. * Arguments: app - The application from which you want to get the attributes. This parameter is optional. * Arguments: key - The key of the attribute you want to get. This parameter is optional. * Statuscodes: * 100 - successfull Example: GET Get the value of the key language of the application parley from the user fregl. Example: ok 100 1 parley language english, german 2007-11-01T22:45:20+01:00 #### 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. * syntax: /v1/person/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: POST postdata: value="italian" Set the value of the key "language" of the application "parley" to "italian". Example: ok 100 #### 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. * syntax: /v1/person/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: POST Delete the attribute with the key "language" and the application "parley". Example: ok 100 ### FRIEND The FRIEND service is for handling friendship relations between people. you can get the friends of a specific person or from yourself. You can invite other persons as a friend and manage the invitations. #### get Gets the list of friends from a person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * syntax: /v1/friend/data/"personid" * HTTP method: GET * Arguments: personid - The person from which you want to get the friendslist. * URL Arguments: page - The page of the friendslist. The size of a page is controlled by the pagesize argument. The first page is 0, the second is 1, ... * URL Arguments: pagesize - The amount of entries per page. * Statuscodes: * 100 - successfull * 101 - data is private * 102 - user not found Example: GET Gets the second page of friends of the person "foobar" Example: ok 100 3 10 cornelius dave fen #### 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. * syntax: /v1/friend/receivedinvitations * HTTP method: GET * 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 Gets the second page of my received invitations. Example: ok 100 1 10 testy #### 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. * syntax: /v1/friend/sentinvitations * HTTP method: GET * 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 Gets the second page of my sent invitations. Example: ok 100 1 10 testy #### 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. * Syntax: /v1/friend/invite/"personid" * Method: POST * 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: POST postdata: message="hi. how are you?" Invites the person "foobar" and send him a message "hi. how are you?" Example: ok #### approve Approve a friendship request. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /v1/friend/approve/"personid" * Method: POST * Arguments: personid - The person you want to approve as a friend. * Statuscodes: * 100 - successful Example: POST Approve the invitation from the user "foobar" Example: ok #### decline Decline a friendship request. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /v1/friend/decline/"personid" * Method: POST * Arguments: personid - The person you want to decline. * Statuscodes: * 100 - successful Example: POST Decline the invitation from the user "foobar" Example: ok #### 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. * Syntax: /v1/friend/cancel/"personid" * Method: POST * Arguments: personid - The person you want to cancel the friendship with. * Statuscodes: * 100 - successful Example: POST Cancel the friendship with the user "foobar" Example: ok ### 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. * Syntax: /v1/message * HTTP method: GET * Result: messagefolder xml * Statuscodes: * 100 - successfull * Example: Example: ok 100 4 0 inbox 27 inbox 1 send 9 send 2 trash 0 trash 3 archive 0 #### list Gets the list of messages from a specific folder. the messages are sorted in chronological order. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /v1/message/"folder" * HTTP method: GET * Arguments: folder - The ID of the folder you want to get. Use the folders method to get the list of folders. * URL Arguments: status - Show only messages with the specified status. Possible values are: 0-unread, 1-read, 2-replyed * URL Arguments: 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 Gets the third page of messages from the folder with the id 1 of person "frank". firstname, lastname and profilepage are from the sender of the message. Example: ok 100 2 10 8490 testy Frank Karlitschek http://www.opendesktop.org/usermanager/search.php?username=Frank Frank 2008-08-10T16:03:59+02:00 1 test message Sorry for bothering but did you ... 8491 testy1 Testy TTT http://www.opendesktop.org/usermanager/search.php?username=testy1 Frank1 2008-08-12T16:03:59+02:00 1 test message Testy 2 ... #### get Get a message. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. the message will be marked as "read" if you access it with this method. * Syntax: /v1/message/"folderid"/"messageid" * HTTP method: GET * Arguments: folderid - The ID of the folder. Use the folders method to get the list of folders. * Arguments: 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 Get the message with the id 42 in the folder 1. firstname, lastname and profilepage are from the sender of the message. Example: ok 100 8490 testy Test TTT http://www.opendesktop.org/usermanager/search.php?username=testy Frank 2008-08-10T16:03:59+02:00 1 test message Sorry for bothering but did you ... #### send Send a message. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /v1/message/"sendfolder" * HTTP method: POST * 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: POST postdata message="coding is fun" subject="hello" to=frank * Send a message to "frank" with the subject "hello" and a messagebody "coding is fun" Example: ok ### ACTIVITY You can use the ACTIVITY services to see what is going on in your friends network. For example who visited you homepage, wo has send you a message and who uploaded a new content to the website. You can also post a microblogging message which is vivible on you profile page and in the activities of your friends. The entries are sorted by timestamp. #### get Gets the list of activities. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /v1/activity * HTTP method: GET * URL Arguments: page - The activities page. The amount of entris per page is controlled by the pagesize argument. The first page is 0, the second is 1, ... * 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 * Gets the third page of the activities of person "frank" Example: ok 100 2 10 42 testy2 Test Te /usermanager/search.php?username=testy2 http://www.opendesktop.org/usermanager/nopic.png 2008-08-01T20:30:19+02:00 6 testy2 has updated: "Extract And Compress" http://www.KDE-Look.org/content/show.php?content=84206 43 foobar2 Foo Bar /usermanager/search.php?username=foobar2 http://www.opendesktop.org/usermanager/nopic.png 2008-08-02T19:38:10+02:00 6 foobar2 has updated: "Arezzo" http://www.KDE-Look.org/content/show.php?content=84403 #### 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 * Example: POST postdata message="coding is fun" * Posts the text "coding is fun" to franks hompage and the activities of franks friends. * Statuscodes: * 100 - successful * 101 - empty message * 102 - user not found Example: ok ### CONTENT #### categories Get a list of all available content categories. * Syntax: /v1/content/categories * HTTP Method: GET * 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: GET Example: ok 100 4 1 KDE Wallpaper 640x480 2 KDE Wallpaper 800x600 3 KDE Wallpaper 1024x768 4 KDE Wallpaper 1280x1024 #### licenses Get a list of all possible licenses. The IDs can be alphanumeric. The IDs should follow "liblicense" if possible. * Syntax: /v1/content/licenses * HTTP Method: GET * 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: GET Example: ok 100 17 1000 3 Artistic 2.0 http://dev.perl.org/perl6/rfc/346.html 6 BSD http://www.opensource.org/licenses/bsd-license.php #### distributions Get a list of all possible distributions. The IDs can be alphanumeric. * Syntax: /v1/content/distributions * HTTP Method: GET * 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: GET Example: ok 100 23 0 2200 Arch 2000 Ark 1100 Debian #### dependencies Get a list of all possible dependencies. * Syntax: /v1/content/dependencies * HTTP Method: GET * 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: GET Example: ok 100 36 0 30 GNOME 1.x 31 GNOME 2.x 20 GTK 1.x #### homepagetypes Get a list of all possible homepagetypes. * Syntax: /v1/content/homepages * HTTP Method: GET * 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: GET Example: ok 100 14 0 &nbsp; 10 Blog 20 Facebook #### list Gets a list of a specific set of contents. * Syntax: /v1/content/data/ * HTTP Method: GET * 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: Gets the second page of the list of the newest contents from categories 1,2,3 and 4 with the string foo in the name. Example: ok 100 2 10 1420 name 11122 2007-11-24T22:41:08+01:00 2007-11-01T22:28:24+01:00 6 KDE Wallpaper (other) Frank http://www.opendesktop.org/usermanager/search.php?username=Frank 5 50 0 http://www.KDE-Look.org/content/preview.php?preview=1&id=1420&file1=1420-1.png&file2=1420-2.png&file3=&name=nameeee http://www.KDE-Look.org/CONTENT/content-pre1/1420-1.png 1422 testy2 11 this is a short summary 2007-11-01T22:45:20+01:00 2007-11-01T22:43:21+01:00 7 KDE Wallpaper (SVG) Frank 8 50 0 http://www.KDE-Look.org/content/preview.php?preview=1&id=1422&file1=1422-1.jpg&file2=1422-2.png&file3=1422-3.png&name=vdfdds222 http://www.KDE-Look.org/CONTENT/content-pre1/1422-1.jpg http://www.KDE-Look.org/img/icon1.png http://www.KDE-Look.org/img/icon2.png http://www.KDE-Look.org/img/icon2.png http://www.KDE-Look.org/CONTENT/content-m1/m1421-1.png 1 Fedora 2.99 http://www.opendesktop.org/content/buy.php?content=1422&id=1 pay item 1 2 Ubuntu 0 http://www.opendesktop.org/content/download.php?content=1422&id=2 free download SUSE 0 http://www.opendesktop.org/content/download.php?content=1422&id=3 free item http://www.KDE-Look.org/content/show.php?content=100 #### get Read content data of one specific content. * Syntax: /v1/content/data/"contentid"/ * HTTP Method: GET * 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: Example: ok 100 100 GradE8 10 Theme/Style for KDE 2.1 Hans 2001-09-28T18:45:40+02:00 2001-09-28T18:45:40+02:00 2 67 his is my first KDE 2.0 theme. It isn't the final version, I must add some icons etc... this is a short summary http://openDesktop.org/feedback http://en.wikipedia.org/foo111 Wikipedia http://myhomepage.com Blog http://www.opendesktop.org/content/donation.php?content=123 0 http://www.opendesktop.org/content/show.php?content=100 22 http://www.opendesktop.org/content/show.php?action=fan&content=100 7 http://www.opendesktop.org/content/show.php?action=knowledgebase&content=100 http://www.KDE-Look.org/content/preview.php?preview=1&id=100&file1=100-1.jpg&file2=&file3=&name=GradE8 http://www.KDE-Look.org/CONTENT/content-pre1/100-1.jpg http://www.KDE-Look.org/CONTENT/content-m1/m100-1.png http://www.KDE-Look.org/img/icon1.png http://www.KDE-Look.org/img/icon2.png http://www.KDE-Look.org/img/icon2.png http://www.KDE-Look.org/content/show.php?content=100 1 Fedora 0 http://www.opendesktop.org/content/download.php?content=1423&id=2 gdfgd22 2 6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy packname repo Fedora 2.99 http://www.opendesktop.org/content/buy.php?content=1423&id=1 gdgg22 6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy packname repo #### 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. * Syntax: /v1/content/download/"contentid"/"itemid" * HTTP Method: GET * 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: Example: ok 100 0 http://www......tar.gz image/jpeg glibc-2.10.1-10.4.i686.rpm http://download.opensuse.org/distribution/11.2/repo/oss/ 6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy #### vote Vote for one specific content. * Syntax: /v1/content/vote/"contentid" * HTTP Method: POST * 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: with the POST variable vote=good Example: ok #### add Add a new content entry: * Syntax: v1/content/add * HTTP Method: POST * 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: Example: ok 100 1234567 #### edit Edit a content entry: * Syntax: v1/content/edit/"12345" * HTTP Method: POST * 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: Example: ok #### delete content entry Delete a content entry: * Syntax: v1/content/delete/"contentid" * HTTP Method: POST * Arguments: contentid - Id of a content * Result: status xml * Statuscodes: * 100 - successful * 101 - no permission to change content * Example: Example: ok #### upload new download file Upload a new download file to a content: * Syntax: v1/content/uploaddownload/"contentid" * HTTP Method: POST * 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: Example: ok #### delete download file Delete the download file from a content: * Syntax: v1/content/deletedownload/"contentid" * HTTP Method: POST * Arguments: contentid - Id of a content * Result: status xml * Statuscodes: * 100 - successful * 101 - no permission to change content * Example: Example: ok #### upload preview image Upload a new preview image for a content: * Syntax: v1/content/uploadpreview/"contentid"/"previewid" * HTTP Method: POST * 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: Example: ok #### delete preview image Delete a preview image from a content: * Syntax: v1/content/deletepreview/"contentid"/"previewid" * HTTP Method: POST * 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: Example: ok #### getrecommendation Gets a list of cross selling for a contentid * Syntax: /v1/content/recommendations/"contentid" * HTTP Method: GET * 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: Gets the second page of the list of recommendations for the content 123 from categories 1,2,3 and 4. Example: ok 100 2 10 1422 1223344 ### 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. * Syntax: /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: Gets the second page of the list of fans of the content with the id 123. The pagesize is 10 Example: ok 100 2 10 Frank 2009-08-18T10:40:09+02:00 Test 2009-07-18T11:41:15+02:00 #### 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. * Syntax: /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: Checks if the user frank is a fan of the content 123 Example: ok 100 fan #### 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. * Syntax: /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 Example: ok 100 #### 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. * Syntax: /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 Example: ok 100 ### 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. * Syntax: /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: Gets the second page of the list of the newest knowledgebase entries from content 123 with the string foo in the name, description or answer. Example: ok 100 2 10 1 not answered 12345 Application testy 2009-02-07T23:14:11+01:00 app question How can I ........ testy2 0 http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12345 > 2 answered 12345 other testy 2009-02-03T21:11:01+01:00 app question 22 How can I 22........ testy2 0 http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12 #### get Read one specific knowledgebase entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: /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: Example: ok 100 1 not answered 12345 Application testy 2009-02-07T23:14:11+01:00 app question How can I ........ testy2 0 http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12345 #### 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. * Syntax: /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: Example: ok 100 ### 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. * Syntax: /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: Gets 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. Example: ok 100 2 10 4 Test Party Party 2010-08-02T00:00:00+02:00 2011-10-03T00:00:00+02:00 Frank Stuttgart Germany 9.183 48.767 2009-05-18T14:03:55+02:00 2 2 http://www.opendesktop.org/events/?id=4 3 Another Party Party 1979-01-01T01:00:01+01:00 1979-01-01T01:00:01+01:00 Frank Stuttgart Germany 1.2 1.1 2009-05-16T00:25:31+02:00 0 1 http://www.opendesktop.org/events/?id=3 #### 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. * Syntax: /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: Example: ok 100 6 bbb here is the description text Party 1970-01-01T00:00:00+01:00 1970-01-01T00:00:00+01:00 Frank Germany 0 0 2009-05-18T18:49:15+02:00 1 2 http://www.opendesktop.org/events/?id=6 http://www.opendesktop.org/CONTENT/event-badge/0/6.png #### add Add a new event entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: 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: Example: ok 100 1234567 #### edit Edit a event entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: 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: Example: ok #### 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. * Syntax: 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: Example: ok ### COMMENTS #### get Gets a list of comments. * Syntax: /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: Gets the second page of the list of comments of the content with the id 123. The pagesize is 10 Example: ok 100 234 vfvvdsx vdxvvsx 0 test 2005-01-29T18:58:40+01:00 50 235 vxvdfvd gfdgfdgfgfgf 1 test 2005-01-29T19:17:06+01:00 60 315 Re: jjjjjjjjjjjjjjj gfdg 0 Frank 2007-03-13T21:34:43+01:00 40 #### add Add a comment. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * Syntax: 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: Example: ok 100 #### 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. * Syntax: /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: with the POST variable vote=4 Example: ok 100 1234567 ### PRIVATE DATA #### get attributes Gets the list of my personal extended attributes. You can store several attributes which are only readable to me. The attributes are key/value pairs with an "app" parameter as namespace. Store data which is only interesting for your application with your application name as a app namespace. If the data is of general interest use "global" as app parameter. The parameter "app" and "key" are optional in the url. So you access all the attributes from yourself or only the attributes from a specific application or the only the value of one specific key. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * syntax: /v1/privatedata/getattribute/"app"/"key" * HTTP method: GET * Arguments: app - The application from which you want to get the attributes. This parameter is optional. * Arguments: key - The key of the attribute you want to get. This parameter is optional. * Statuscodes: * 100 - successfull Example: GET Get the value of the key language of the application parley from myself. Example: ok 100 1 parley language english, german 2007-11-01T22:45:20+01:00 #### set attribute Set a attribute. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * syntax: /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: POST postdata: value="italian" Set the value of the key "language" of the application "parley" to "italian". Example: ok 100 #### delete attribute Delete a attribute. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. * syntax: /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: POST Delete the attribute with the key "language" and the application "parley". Example: ok 100 ### FORUM #### list Gets a list of forums. * syntax: /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: Gets the second page of the list of forums. The pagesize is 10 Example: ok 100 234 vfvvdsx test 2005-01-29T18:58:40+01:00 http://forum.example.org/images/forum-img.png 0 123 876 yheweq foobar 2005-01-29T18:58:40+01:00 http://forum.example.org/img/forum-icon.gif 1 234 cameras new forum 2005-01-29T18:58:40+01:00 http://forum.example.org/images/icon.jpg 0 5 789 #### topics/list Gets a list of a specific set of topics. * syntax: /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: Gets 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. Example: ok 100 2 10 1 123 testy 2009-02-07T23:14:11+01:00 Random forum post Just testing 0 #### 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. * syntax: /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: Example: ok 100 ### 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 " * 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: POST postdata: name="A Project" developers[0][name]="Frank Karlitschek" developers[0][url]="[[mailto:karlitschek@kde.org|mailto:karlitschek@kde.org]]" developers[1][name]="Dan jensen" developers[1][url]="[[mailto:admin@leinir.dk|mailto:admin@leinir.dk]]" This creates a new project and inserts the two listed developers as information on the project. Example: ok 100 122 ##### 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: GET This might yield the following XML output: ok 100 122 A Project 1.0pre1 Creative Commons Attribution Share-Alike 2.0 http://somesite.com/ Frank Karlitschek <karlitschek@kde.org> Dan Jensen <admin@leinir.dk> A neat little project which does something A long description of the project which even cleverly includes multiple lines # # 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...) ##### 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: POST This might yield the following XML output: ok 100 ##### 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 " * 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: POST postdata: name="A Project" summary="A neat little project which does something" This might yield the following XML output: ok 100 ##### 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: GET This might yield the following XML output (where the user has exactly one project): ok 100 122 A Project 1.0pre1 Creative Commons Attribution Share-Alike 2.0 http://somesite.com/ Frank Karlitschek <karlitschek@kde.org> Dan Jensen <admin@leinir.dk> A neat little project which does something A long description of the project which even cleverly includes multiple lines ##### 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: POST This might yield the following XML output: ok 100 #### 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: GET This might yield the following XML output: ok 100 2 1 mbs frank password 7 2 1 frank password ##### 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: POST postdata: type=1 typeid="mbs" This might yield the following XML output: ok 100 7 ##### 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: POST postdata: login="frank" password="bet123ter" This might yield the following XML output: ok 100 ##### 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: GET This might yield the following XML output: ok 100 7 2 1 frank bet123ter ##### 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: POST This might yield the following XML output: ok 100 #### 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: GET This might yield the following XML output: ok 100 1 Some Build Service http://bs.some.com/user/new 1 i386 2 x86_64 3 armv5 ##### 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: GET This might yield the following XML output: ok 100 1 Some Build Service http://bs.some.com/user/new 1 i386 2 x86_64 3 armv5 #### 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: GET This might yield the following XML output: ok 100 12 122 mbs 2 armv5 job 12 1 0.56 http://bs.some.com/job/54322 18 122 obs 4 armv5 job 14 1 0.88 http://bs.some.com/job/54324 ##### 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: POST This might yield the following XML output: ok 100 616 ##### 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: POST This might yield the following XML output: ok 100 ##### 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: GET This might yield the following XML output: ok 100 12 122 mbs 2 armv5 job 12 1 0.56 http://bs.some.com/job/54322 ##### 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: GET This might yield the following XML output: ok 100 -- Found GCC: /usr/bin/gcc -- Found X11: /usr/lib64/libX11.so (etc etc) #### Publishing ##### getpublishingcapabilities List all the available publishers. In the case of an authenticated user, the function will return only the publishers that the user has an account with. Authentication is done by sending a Basic HTTP Authorisation header. Status 102 is informational and in essence is a success. It is meant as a convenient way of finding out whether to bother parsing the list of publishers. * Syntax: /v1/buildservice/publishing/getpublishingcapabilities * HTTP method: GET * URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ... * URL argument: pagesize - The amount of entries your get per page. * Result: * publisheridlist - a list of publishers, see buildservice/publishing/getpublisher * Statuscodes: * 100 - success * 101 - no such user * 102 - user has not registered with any publishers Example: GET This might yield the following XML output: ok 100 1 Some App Store http://store.some.com/user/new Name string 256 true Description longtext 4294967296 false Category item 0 true i386 x86_64 armv5 2 Somewhere http://store.some.where/register i386 ##### 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: GET This might yield the following XML output: ok 100 1 Some App Store http://store.some.com/user/new Name string 256 true Description longtext 4294967296 false Category item 0 true i386 x86_64 armv5 ##### 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: POST This might yield the following XML output: ok 100 ##### 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: POST postdata: fields[0]["name"]="Name" fields[0]["fieldtype"]="string" fields[0]["data"]="A Project" fields[1]["name"]="Category" fields[1]["fieldtype"]="item" fields[1]["data"]="Nifty" This might yield the following XML output: failed 103 The item "Nifty" does not exist in the list of possible options. The options are: "Game", "Productivity", "Gadget" ##### 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: GET This might yield the following XML output: ok 100 Name string A Project Summary string A neat little project which does something Category item Gadget --- [[CategoryHomepage]]