Open Collaboration Services v1.6

Frank Karlitschek MailTo(karlitschek AT kde.org)

OCS Mailinglist

Changelog

Differences between 1.5 and 1.6 PERSON:

Purpose

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

Examples

Naming

Requirements

Performance / Scalability

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

Security

the data transfer should be encrypted if possible.

Privacy

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

Vendor Independent

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

Architecture

REST

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

SSL

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

Authentication

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

example login/password

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

example api key

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

Proxy

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

Date Format

All date and time data is in ISO 8601 format.

Services

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

At the moment there are the following services:

Error Reporting

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

Versioning

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

Provider files

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

<providers>

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

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

</providers>

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

Service Specifications

CONFIG

config

get some basic API configuration information

PERSON

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

check

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

add

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

search

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

Example: 

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

get

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

get 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.

edit

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

balance

Get the account balance of a user.

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.

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.

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.

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.

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.

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.

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.

approve

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

decline

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

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.

MESSAGE

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

folders

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

list

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

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.

send

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

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.

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.

CONTENT

categories

Get a list of all available content categories.

licenses

Get a list of all possible licenses. The IDs can be alphanumeric. The IDs should follow "liblicense" if possible.

distributions

Get a list of all possible distributions. The IDs can be alphanumeric.

dependencies

Get a list of all possible dependencies.

homepagetypes

Get a list of all possible homepagetypes.

list

Gets a list of a specific set of contents.

get

Read content data of one specific content.

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.

vote

Vote for one specific content.

add

Add a new content entry:

edit

Edit a content entry:

delete content entry

Delete a content entry:

upload new download file

Upload a new download file to a content:

delete download file

Delete the download file from a content:

upload preview image

Upload a new preview image for a content:

delete preview image

Delete a preview image from a content:

getrecommendation

Gets a list of cross selling for a contentid

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

edit

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

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.

COMMENTS

get

Gets a list of comments.

add

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

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.

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.

set attribute

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

delete attribute

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

FORUM

list

Gets a list of forums.

Example:

<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message></message>
</meta>
<data>
<forum>
 <id>234</id>
 <name>vfvvdsx</name>
 <description>test</description>
 <date>2005-01-29T18:58:40+01:00</date>
 <icon>http://forum.example.org/images/forum-img.png</icon>
 <childcount>0</childcount>
 <children></children>
 <topics>123</topics>
</forum>
<forum>
 <id>876</id>
 <name>yheweq</name>
 <description>foobar</description>
 <date>2005-01-29T18:58:40+01:00</date>
 <icon>http://forum.example.org/img/forum-icon.gif</icon>
 <childcount>1</childcount>
 <children>
    <forum>
      <id>234</id>
      <name>cameras</name>
      <description>new forum</description>
      <date>2005-01-29T18:58:40+01:00</date>
      <icon>http://forum.example.org/images/icon.jpg</icon>
      <childcount>0</childcount>
      <children></children>
      <topics>5</topics>
    </forum>
 </children>
 <topics>789</topics>
</forum>
</data>
</ocs>

topics/list

Gets a list of a specific set of topics.

Example:

<?xml version="1.0"?>
<ocs>
<meta>
 <status>ok</status>
 <statuscode>100</statuscode>
 <message></message>
 <totalitems>2</totalitems>
 <itemsperpage>10</itemsperpage>
</meta>
<data>
 <topic details="detail">
  <id>1</id>
  <forumid>123</forumid>
  <user>testy</user>
  <changed>2009-02-07T23:14:11+01:00</changed>
  <subject>Random forum post</subject>
  <content>Just testing</content>
  <comments>0</comments>
 </topic>
</data>

forum/topics/add

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

Example:

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

BUILDSERVICE

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

Projects

create

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

This creates a new project and inserts the two listed developers as information on the project.

Example:

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

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <project>
      <projectid>122</projectid>
      <name>A Project</name>
      <version>1.0pre1</version>
      <license>Creative Commons Attribution Share-Alike 2.0</license>
      <url>http://somesite.com/</url>
      <developers>Frank Karlitschek &lt;karlitschek@kde.org&gt;
Dan Jensen &lt;admin@leinir.dk&gt;</developers>
      <summary>A neat little project which does something</summary>
      <description>A long description of the project

which even cleverly includes multiple lines</description>
      <requirements></requirements>
      <specfile>#
# spec file for package a-project
#
# Copyright (C) 2010 Frank Karlitschek (mailto:karlitschek@kde.org)
# Copyright (C) 2010 Dan Jensen (mailto:admin@leinir.dk)
#

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

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

%description
A long description of the project

which even cleverly includes multiple lines

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

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

This might yield the following XML output:

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

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

This might yield the following XML output:

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

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

This might yield the following XML output (where the user has exactly one project):

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

which even cleverly includes multiple lines</description>
        <requirements></requirements>
        <specfile></specfile>
      </project>
    </projectlist>
  </data>
</ocs>
uploadsource

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

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

This might yield the following XML output:

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

Remote Accounts

list

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <remoteaccountslist>
      <remoteaccount>
        <id>2</id>
        <type>1</type>
        <typeid>mbs</typeid>
        <data></data>
        <login>frank</login>
        <password>password</password>
      </remoteaccount>
      <remoteaccount>
        <id>7</id>
        <type>2</type>
        <typeid>1</typeid>
        <data></data>
        <login>frank</login>
        <password>password</password>
      </remoteaccount>
    </remoteaccountslist>
  </data>
</ocs>
add

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

This might yield the following XML output:

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

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

This might yield the following XML output:

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

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <remoteaccount>
        <id>7</id>
        <type>2</type>
        <typeid>1</typeid>
        <data></data>
        <login>frank</login>
        <password>bet123ter</password>
    </remoteaccount>
  </data>
</ocs>
remove

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

This might yield the following XML output:

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

Build Services

list

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

This might yield the following XML output:

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

Get a the information on a particular build service.

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildservice>
      <id>1</id>
      <name>Some Build Service</name>
      <registrationurl>http://bs.some.com/user/new</registrationurl>
      <supportedtargets>
        <target>
          <id>1</id>
          <name>i386</name>
        </target>
        <target>
          <id>2</id>
          <name>x86_64</name>
        </target>
        <target>
          <id>3</id>
          <name>armv5</name>
        </target>
      </supportedtargets>
    </buildservice>
  </data>
</ocs>

Build Jobs

list

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildjobs>
      <buildjob>
        <id>12</id>
        <project>122</project>
        <buildservice>mbs</buildservice>
        <target>2</target>
        <name>armv5 job 12</name>
        <status>1</status>
        <progress>0.56</progress>
        <url>http://bs.some.com/job/54322</url>
        <message></message>
      </buildjob>
      <buildjob>
        <id>18</id>
        <project>122</project>
        <buildservice>obs</buildservice>
        <target>4</target>
        <name>armv5 job 14</name>
        <status>1</status>
        <progress>0.88</progress>
        <url>http://bs.some.com/job/54324</url>
        <message></message>
      </buildjob>
    </buildjobs>
  </data>
</ocs>
create

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

This might yield the following XML output:

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

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

This might yield the following XML output:

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

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <buildjob>
      <id>12</id>
      <project>122</project>
      <buildservice>mbs</buildservice>
      <target>2</target>
      <name>armv5 job 12</name>
      <status>1</status>
      <progress>0.56</progress>
      <url>http://bs.some.com/job/54322</url>
      <message></message>
    </buildjob>
  </data>
</ocs>
getoutput

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <output>-- Found GCC: /usr/bin/gcc
-- Found X11: /usr/lib64/libX11.so
(etc etc)
    </output>
  </data>
</ocs>

Publishing

getpublishingcapabilities

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

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

This might yield the following XML output:

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

Get the descriptive information about a publisher.

This might yield the following XML output:

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

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

This might yield the following XML output:

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

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

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>failed</status>
    <statuscode>103</statuscode>
    <message>The item "Nifty" does not exist in the list of possible options. The options are: "Game", "Productivity", "Gadget"</message>
  </meta>
</ocs>
getfields

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

This might yield the following XML output:

<?xml version="1.0"?>
<ocs>
  <meta>
    <status>ok</status>
    <statuscode>100</statuscode>
    <message></message>
  </meta>
  <data>
    <fields>
      <field>
        <name>Name</name>
        <fieldtype>string</fieldtype>
        <data>A Project</data>
      </field>
      <field>
        <name>Summary</name>
        <fieldtype>string</fieldtype>
        <data>A neat little project which does something</data>
      </field>
      <field>
        <name>Category</name>
        <fieldtype>item</fieldtype>
        <data>Gadget</data>
      </field>
    </fields>
  </data>
</ocs>

CategoryHomepage