-
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 when 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 won't 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)
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.