Skip to content
This repository has been archived by the owner on Jul 6, 2020. It is now read-only.

API 2.0

Jump to bottom
Bernhard Posselt edited this page Sep 26, 2015 · 2 revisions

Disclaimer: This has not yet been implemented and is still a draft

The News app offers a RESTful API

API stability contract

The API level will change if the following occurs:

  • A field of an object is removed
  • A field of an object has a different datatype
  • The meaning of an API call changes

The API level will not change if:

  • The app version is changed (e.g. 4.0.1.2 instead of 4.0 or 4.001)
  • A new attribute is added (e.g. each item gets a new field "something": 1)
  • The order of the JSON attributes is changed on any level (e.g. "id":3 is not the first field anymore, but the last)

You have to design your app with these things in mind!:

  • Don't depend on the order of object attributes. In JSON it does not matter where the object attribute is since you access the value by name, not by index
  • Don't limit your app to the currently available attributes. New ones might be added. If you don't handle them, ignore them
  • Use a library to compare versions, ideally one that uses semantic versioning

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/2.0

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/2.0/feeds

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

Authorization: Basic $CREDENTIALS

where $CREDENTIALS is:

base64(USER:PASSWORD)

How To Sync

This is a small overview over how you should sync your articles with the ownCloud News app. For more fine-grained details about the API jump to the specification overview further down.

All routes are given relative to the base API url (e.g.: https://yourowncloud.com/index.php/apps/news/api/2.0)

Initial Sync

The intial sync happens, when a user adds an ownCloud account in your app. In that case you should fetch all feeds, folders and unread or starred articles from the News app. Do not fetch all articles, not only because it syncs faster, but also because the user is primarily interested in unread articles. To fetch all unread and starred articles, you must call 4 routes:

TBS

The JSON response structures can be viewed on their respective specification pages.

Syncing

When syncing, you want to push read/unread and starred/unstarred items to the server and receive new and updated items, feeds and folders. To do that, call the following routes:

TBS

Accessing API from a web application

An example request in jQuery would look like this:

$.ajax({
	type: 'GET',
	url: 'https://yourowncloud.com/index.php/apps/news/api/2.0/version',
	contentType: 'application/json',
	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/2.0/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

Clone this wiki locally