API 1.2

The News app 1.2 offers a RESTful API

Authentication & Basics

Because REST is stateless you have to send user and password each time you access the API. Therefore running ownCloud with SSL is highly recommended otherwise everyone in your network can log your credentials.

The base URL for all calls is:

https://yourowncloud.com/index.php/apps/news/api/v1-2/

All defined routes in the Specification are appended to this url. To access all feeds for instance use this url:

https://yourowncloud.com/index.php/apps/news/api/v1-2/feeds

Credentials need to be passed as an HTTP header using HTTP basic auth:

Authorization: Basic $CREDENTIALS

where $CREDENTIALS is a base64(USER:PASSWORD)

Accessing API from a web application

News 1.401 implements CORS which allows web applications to access the API. To access the API in a webapp you need to send the correct authorization header instead of simply putting auth data into the URL!. An example request in jQuery would look like this:

$.ajax({
	type: 'GET',
	url: 'https://yourowncloud.com/index.php/apps/news/api/v1-2/version',
	contentType: 'application/json',
	xhrFields: {
		widthCredentials: true
	},
	success: function (response) {
		// handle success
	},
	error: function () {
		// handle errors
	},
	beforeSend: function (xhr) {
		var username = 'john';
		var password = 'doe';
		var auth = btoa(username + ':' + password);
		xhr.setRequestHeader('Authorization', 'Basic ' + auth);
	}
});

An example with AngularJS would look like this:

angular.module('YourApp', [])
    .config(['$httpProvider', '$provide', function ($httpProvider, $provide) {
        $provide.factory('AuthInterceptor', ['Credentials', '$q', function (Credentials, $q) {
            return {
                request: function (config) {
                    // only set auth headers if url matches the api url
                    if(config.url.indexOf(Credentials.url) === 0) {
                        auth = btoa(Credentials.userName + ':' + Credentials.password);
                        config.headers['Authorization'] = 'Basic ' + auth;
                    }
                    return config || $q.when(config);
                }
            };
        }]);
        $httpProvider.interceptors.push('AuthInterceptor');
    }])
    .factory('Credentials', function () {
        return {
            userName: 'user',
            password: 'password',
            url: 'https://yourowncloud.com/index.php/apps/news/api'
        };
    })
    .run(['$http', function($http) {
        $http({
            method: 'GET',
            url: 'https://yourowncloud.com/index.php/apps/news/api/v1-2/version'
        }).success(function (data, status, header, config) {
            // handle success
        }).error(function (data, status, header, config) {
            // handle error
        });
    }]);

Input

In general the input parameters can be in the URL or request body, the App Framework doesnt differentiate between them.

So JSON in the request body like:

{
  "id": 3
}

will be treated the same as

/?id=3

It is recommended though that you use the following convention:

• GET: parameters in the URL
• POST: parameters as JSON in the request body
• PUT: parameters as JSON in the request body
• DELETE: parameters as JSON in the request body

Output

The output is JSON.

Specification

• Generic
• Folders
• Feeds
• Items
• Cron