-
Notifications
You must be signed in to change notification settings - Fork 106
API 1.2
The News app 1.2 offers a RESTful API
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
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:
base64(USER:PASSWORD)
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/v1-2)
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:
- unread articles: GET /items?type=3&getRead=false&batchSize=-1
- starred articles: GET /items?type=2&getRead=true&batchSize=-1
- folders: GET /folders
- feeds: GET /feeds
The JSON response structures can be viewed on their respective specification pages.
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:
- Notify the News app of unread articles: PUT /items/unread/multiple {"items": [1, 3, 5] }
- Notify the News app of read articles: PUT /items/read/multiple {"items": [1, 3, 5]}
- Notify the News app of starred articles: PUT /items/starred/multiple {"items": [{"feedId": 3, "guidHash": "adadafasdasd1231"}, ...]}
- Notify the News app of unstarred articles: PUT /items/unstarred/multiple {"items": [{"feedId": 3, "guidHash": "adadafasdasd1231"}, ...]}
- Get new folders: GET /folders
- Get new feeds: GET /feeds
- Get new items and modified items: GET /items/updated?lastModified=12123123123&type=3
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',
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
});
}]);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
The output is JSON.